Reconciliation that converges

A design system lives in two places at once. It lives in a folder of markdown documents that humans author (patterns, tokens, decisions, rules), and it lives in a database that agents, validators, and search query. The two have to stay in sync, and neither side is authoritative.

Most sync systems solve this by declaring a winner. Style Dictionary regenerates output from source. Figma tokens plugins push one-way. Storybook's CSF treats code as truth and docs as derived. That works until both sides mutate between runs (a rename in source while the canonical store deprecated an entry), and then the naive importer creates duplicates, loses history, or silently drops the conflict.

This post is the mechanism we settled on. It has four moving parts, and each one is standard. The combination is where the work is.

Convergence is not a sync. It's a fixed point.

1. Deterministic delta keys

Every candidate change computes a delta_key. It is a stable hash over (artifact_type, source_path, change_type, prior_state_hash, next_state_hash). The same change proposed twice produces the same key. The same field edited twice in different directions produces different keys. The delta_key is the unit of idempotency.

2. Advisory locks, per delta

Before applying a delta, the worker takes a Postgres advisory lock keyed on the hash of the delta_key. The scope is the delta, not the row. Two independent changes to the same pattern (a rename and a description edit) can proceed in parallel. The lock exists to serialize concurrent appliers of the same delta, not to serialize the table.

3. Unique-violation as a success signal

Applying a delta does two things in one transaction: mutate the canonical tables and insert a row into reconciliation_audit with the delta_key as a unique constraint. If the audit insert raises a 23505 unique-violation, another worker already applied this exact delta. That isn't an error. It's confirmation that the canonical state already reflects the change. The worker rolls back its inner transaction, releases its advisory lock, and continues as if it had done the work itself. Because by definition, it has.

This is the move that makes concurrent reconciliation tractable. You don't coordinate the workers. You let them race, and the database refuses the second one with an error that means you're done.

4. Full-state audit, not operation logs

Every applied delta writes a single row containing prior_state and next_state as complete JSONB snapshots of the artifact. Not a diff. Not a command ("set name to X"). The whole row, before and after.

The reason is reversal. undo_reconciliation(batch_id) walks the audit in reverse and writes prior_state back. It doesn't need to know the schema, it doesn't need to invert operations, it doesn't need to handle cascading re-derivations. The snapshot is the inverse.

Soft-deletes are part of this. We never issue DELETE. Removal is lifecycle_state = 'removed' on the identity row; the artifact data stays. Undoing a removal is an update from removed back to active, and the prior_state snapshot already describes it.

5. Frontmatter re-emission

Here's the close. After the canonical store mints an identity for an added delta, we write that artifact_id back into the source document's YAML frontmatter and commit it. On the next sync, the source carries its canonical identity with it.

This flips three things at once:

• Renames are updates, not add-and-delete. When an author renames UserCard to ProfileCard, the detector sees the same artifact_id with a different name, and emits one update. The old naive pipeline would have seen "one missing, one new."
• Identity is portable. Branches, forks, and cross-repo moves all carry the artifact_id in the document. No side-channel lookup table needs to be consulted. No environment-specific ID mapping.
• The detector becomes stateless. It reads current source and current canonical, computes deltas, and is done. No memory of prior syncs. That's what makes retries and partial failures safe. There's nothing to get out of phase.

The whole sequence

Written out: detect deltas by diffing source and canonical. Plan them as added / updated / removed / renamed. Apply each delta under its own advisory lock, with a full-state audit row guarding idempotency. Emit minted identities back to source frontmatter and commit. Verify by re-running detect. The expected result is an empty delta set. If it isn't, the only thing to retry is emission.

Each of those steps is something you'd find in an event-sourcing textbook, a Postgres performance guide, or a static site generator. Individually they're unremarkable. Composed in that order, with those contracts, the system converges.

What we got from it

Concurrent workers can reconcile the same batch without coordination. A crashed worker releases its lock at connection close and another picks up the remainder. If the partial work already landed, the audit insert returns 23505 and we move on. A bad sync is reversed by replaying the audit in reverse. A rename is one row changed, not two rows churned. And the detector is a pure function of (source, canonical), which means the same drift analysis runs locally during authoring, in CI, and in scheduled jobs, all agreeing.

preset AI runs this loop every time upstream drifts. The design system converges. The audit trail is the receipt.

Note on prior art. This post is also a defensive publication. The combination of deterministic delta keys, advisory-lock-per-delta, unique-violation-as-success idempotency, full-state audit snapshots, soft-delete-only lifecycle, and frontmatter re-emission of canonical identity, as applied to bidirectional design-system artifact convergence, is described here in sufficient detail to establish prior art as of April 19, 2026. This disclosure is licensed CC0 / public domain.