Skip to content

I0810 — A content-hash manifest that makes a second sync cheap

Implement the manifest: one row per source with its path, content hash, extractor version and the node ids it produced, written beside the generated graph, compared on every sync, and used so that a sync with no source change does no extraction and says so.

READY wave 4 · p1 · implementation profile · runs alone

Part of M003 — A session is a durable envelope, and knowledge is compiled from what is already canonical.

Ready. Every dependency is done, so majordomus plan start I0810 will be accepted.

Objective

Implement the manifest: one row per source with its path, content hash, extractor version and the node ids it produced, written beside the generated graph, compared on every sync, and used so that a sync with no source change does no extraction and says so.

Why

Without a manifest, every query is tempted to rebuild and every rebuild is a full one. The manifest is what makes staleness detectable without mutating anything, which is what lets the read-only commands stay read-only.

Current state

Nothing is generated and nothing is cached. The site generator's --check mode is the precedent for a command that reports drift between canonical input and derived output without regenerating it.

Desired state

`knowledge sync` writes the manifest with the graph. `knowledge sync --check` compares source hashes against the manifest and exits non-zero when they differ, writing nothing. `knowledge status` reports fresh or stale and names the sources that moved. A no-op sync is measurably cheaper than a cold one, and the measurement is recorded.

Scope

  • lib/knowledge.sh
  • lib/knowledge.awk
  • .gitignore
  • test/cases/68_knowledge_manifest.sh

Out of scope

  • Search
  • Any automatic rebuild triggered by a read

Dependencies

What waits on this

Acceptance criteria

  • A second sync with no source change reports no work and leaves the generated files byte-identical
  • Editing one source changes that source's manifest row and the nodes derived from it, and no other row
  • sync --check writes nothing and exits non-zero when a source has moved
  • The extractor version is part of the manifest, so a change to the extractor invalidates it
  • The measured cost of a no-op sync and of a cold sync on this repository is recorded as evidence

Validation

  • bash test/run.sh 68_knowledge_manifest

Evidence required

  • sync_idempotent
  • noop_is_cheaper

Evidence

None recorded. Every token above needs a command or an artifact behind it before this issue can be completed; narrative is refused.

Risk

If a no-op sync is not materially cheaper than a cold one, the manifest has failed and should be removed rather than kept as decoration. The measurement is the acceptance criterion, not the design.

Timeline

started
—
verified
—
completed
—

Those three fields, the evidence above and the state of the dependencies are all the status is made of. There is no status field to disagree with them.

Canonical record: .ai/repo/project/issues/I0810.yaml. Read it back with majordomus plan show I0810.