← Blog

· Hive AI

Knolo Sync: Why Diverged Knowledge Images Never Merge Silently

Knolo KIP-0012 to KIP-0016 compare two Knowledge Images, fast-forward only a direct child, and merge a divergence only after every conflict is decided and authorized.

Knolo is the open-source, local-first Knowledge Image runtime and format: Apache-2.0, published on npm as @knolo/core. Because a Knolo Knowledge Image is a file you can copy, two copies will eventually drift apart. The Knolo sync proposals answer one question first: when two copies disagree, who is allowed to decide what happens next? Their answer is never the runtime by itself.

This note reads five Knolo Improvement Proposals in the public source tree, KIP-0012 through KIP-0016, as one design. Each is marked "foundation implementation" in the Knolo core repository on GitHub. As the Knolo specifications page says, until specification records are numbered and adopted, the working contract lives in public source and documentation. None of these is an adopted standard yet.

Knolo sync starts with a summary, not a transfer

KIP-0012, Sync Summary V1, defines the first safe boundary. A sync summary commits to an image's state root, commit digest, sequence, parent commits, object root, event root and, optionally, its authority keyring root. The runtime compares two verified images and returns exactly one of four relations:

  • equal: both images identify the same state.
  • local-ahead: the local commit directly names the remote commit as a parent.
  • remote-ahead: the remote commit directly names the local commit as a parent.
  • diverged: neither state is a direct fast-forward of the other.

For remote-ahead, the plan lists the remote object and event IDs that are missing locally. For diverged, no transfer set and no merge set are produced. The summary and plan roots use canonical CBOR and domain-separated SHA-256, so two runtimes comparing the same pair of images should reach the same relation and the same roots.

In @knolo/core this boundary is compareKnowledgeSyncImagesV5.

Knolo fast-forward: the only import that needs no decision

KIP-0013, Verified Fast-Forward Import V1, is the one case where a store may adopt another image without anyone choosing between alternatives. All of these must hold:

  • both images mount and verify;
  • the remote commit directly names the current local commit as a parent;
  • any supplied authority keyring roots agree.

Equal, local-ahead and diverged states are rejected as fast-forward imports. Nothing is partially copied, and no implicit merge is attempted. In the Node durable store, the verified remote bytes are written with a temporary file, fsync, atomic replace and directory fsync before the new snapshot is published, and an active writer transaction blocks the operation. The same rule shows up in the Knolo Exchange tooling, where adopting a received image fast-forwards a store that is directly behind it and leaves an ahead or diverged store unchanged.

Knolo divergence: a plan you can verify, not a winner

KIP-0015, Divergent Merge Planning V1, is read-only. Given two verified direct child images and their shared verified ancestor, the runtime returns a deterministic merge plan. The plan lists branch-only objects and events, plus conflicts for competing event targets, view roots and commit metadata roots.

The plan is content-addressed under the knolo:merge-plan:v1 domain, and verifyKnowledgeMergePlanV5 recomputes every summary and plan root before it accepts a plan from outside. Missing, unrelated, non-divergent or malformed ancestors are rejected, and the keyring roots must match.

What KIP-0015 explicitly does not do matters just as much: it does not pick a winner, rewrite an object, apply a merge commit or change either branch.

Knolo merge: every conflict decided, then authorized

KIP-0016, Authorized Merge Application V1, is the only path from a divergence to a merged image. The caller must supply:

  1. exactly one local-or-remote decision for every conflict in the plan; and
  2. an authorization callback that approves the complete plan and the normalized resolution.

The runtime verifies the plan against the local, remote and ancestor images before it calls the authorization callback. An accepted resolution produces a new immutable image whose commit names both branch commits as parents. It is built from the shared ancestor: branch-only objects are kept, and for each event-target conflict only the events from the selected side are kept. Roots and views are recomputed, and the result is mounted and verified before it is returned. A rejected, unresolved or failed merge leaves the current snapshot unchanged.

The callback is host-injected. KIP-0016 does not say who the authority is or how it is reached. It only guarantees that one was asked, about the whole plan, before anything changed.

Knolo sync messages carry metadata, not bytes

KIP-0014 adds signed sync requests and responses: sender, nonce-derived request ID, expiry window, the advertised summary and the requested IDs, with Ed25519 helpers and a bounded in-memory replay cache. A malformed, expired, tampered, replay-shaped or keyring-incompatible message fails closed. These messages do not open sockets or move object bytes; transport stays a host choice. Durable replay-cache persistence and complete image transfer are defined later, by KIP-0023.

What the Knolo sync design leaves open

The proposals list their own open edges: automatic conflict selection, multi-writer coordination, remote writes and network transport are all outside these five proposals. That is a deliberate trade. A Knolo runtime will tell you exactly how two Knowledge Images relate, hand you a plan whose roots anyone can recompute, and stop. Deciding is left to a named host and its authority, which is where an open format can let different deployments use different policies without breaking the bytes.

Status, support windows and migration notes for these proposals will belong on the Knolo lifecycle page once that matrix is published.

Read the Knolo sources

Knolo is built by Hive AI and released as open source under Apache-2.0.