[theaspirational]

What this adds

• bundle_uid in meta/purpose.md: one id per bundle. okfy init writes it.
  It lives in purpose.md rather than index.md, whose frontmatter may declare
  only okf_version (§8).
• okf_id in each concept page's frontmatter, for pages outside meta/. It
  travels with the file, so a renamed or moved page keeps it. okfy review accept gives a created or superseding page a fresh one. It keeps the page's
  okf_id, and purpose.md's bundle_uid, through an update, whatever the
  proposed text carries. okfy refine refuses text that changes either one.
• Reserved-page identity. index.md, log.md, the generated root docs and
  meta/* carry no okf_id. Their names are fixed, so they are addressed as
  bundle_uid plus the bundle-relative path.
• Scheme links. Any RFC 3986 scheme (other-tool://x/page) is now an
  external link, not only http(s)/mailto. Before, such a link resolved as a
  local path and warned W_DANGLING_LINK, or vanished without a word if it had
  no .md. okfy links and the MCP okfy_links list a page's external targets
  under external. They read them from the page, so the retrieval fingerprint
  does not move.
• okfy migrate ids <bundle> backfills both ids into an existing bundle.
  A key already present is never touched, so a rerun writes nothing. It commits
  past the policy hook, like okfy stale.
• Validation:
  • Warnings: W_BUNDLE_UID_MISSING, W_OKF_ID_MISSING (an older bundle stays
    green).
  • Errors: E_BUNDLE_UID, E_OKF_ID (a blank or non-string id) and
    E_OKF_ID_DUPLICATE (a page copied instead of moved).
• Related corpus fixes:
  • A bundle embedded in the corpus at any path (not only .okf/) is left out
    of the manifest, the survey and the update diff. It is recognised by
    meta/purpose.md (type: Purpose) and meta/corpus.md
    (type: CorpusSnapshot), not by file names alone.
  • okfy init --embed no longer lists its own bundle.
  • meta/corpus.md records manifest_digest, a sha256 over the manifest that
    was actually read. E_MANIFEST_DIGEST reports a manifest that no longer
    matches it.

Why

A concept id is its path, so it changes when a page moves. Anything outside
the bundle that points at a page, such as a cross-project reference or an
okf://-style URI in another tool (orgasmic, for example), needs an id that
survives renames and edits. bundle_uid + okf_id is that id, and
bundle_uid + path covers the reserved pages.

How ids are derived

• New ids (init, accept) are random uuid4s.
• Backfilled ids (migrate ids) are uuid5s that every clone derives alike,
  so two clones migrating offline agree:
  • bundle_uid comes from the commit that created the current
    meta/purpose.md, plus the bundle's path inside its repo.
  • okf_id comes from bundle_uid, the commit that created the page, and the
    page's path.
  • "Created" means the latest add of that path along the first-parent
    mainline, with a merge diffed against its first parent. A file that was
    deleted and later replaced at the same path is a new lineage and gets a new
    id. A file that was never committed, or whose path was last deleted, gets a
    random id.
• The git read is pinned against clone-local settings: grafts, replace refs,
  rename detection, signatures, root-commit diffs, output encoding, colour,
  pathspec magic, Unicode precomposition and locale. The full list is in
  _pinned_git's docstring. A git failure other than "not a repository" or
  "no commits" raises instead of silently minting a random id.
• Once written, an id is never recomputed.

Documented limits (README and docs/OKF-COMPATIBILITY.md):

• Shallow clones. A shallow clone that does not reach the creating commit
  derives a different id. Migrate from a full clone (git fetch --unshallow).
• core.worktree. A clone whose core.worktree points elsewhere reads a
  different bundle path, and so derives a different bundle_uid. This is repo
  layout, with no neutral value to pin.

Migration note

Existing bundles keep working. They only gain the two *_MISSING warnings.
Run okfy migrate ids <bundle> once, from a full, ordinary clone, and commit
or push the result, so every other clone receives the persisted ids rather than
deriving its own.

The backfill inserts one frontmatter line and leaves the owner's YAML
(comments, quoting, key order) byte-for-byte as it was. Flow-style frontmatter
({type: Note, ...}) is re-serialized instead, and the output is checked to
parse before it is written.

To rename a page, move the file. Deleting it and writing a new page makes a new
id.

Tests

26 tests in core/tests:

• test_identity.py:
  • init mints bundle_uid
  • migrate backfills, keeps owner comments, and a rerun is a no-op
  • reserved and meta/ pages carry no okf_id
  • migrate commits past the policy hook
  • blank and duplicate ids are errors
  • a moved page keeps its id
  • accept-update keeps okf_id and bundle_uid
  • accept-create and supersede mint fresh ids, and supersede does not copy
    bundle_uid
  • refine refuses an id change
  • two offline clones migrate to the same ids
  • a page or bundle replacing a deleted one gets its own id
  • paths that differ only by a space get distinct uids
  • flow-style frontmatter stays valid
  • a page restored by a modify/delete merge gets the same id in every clone
  • derived ids ignore hostile clone-local git config and environment (signed
    history, a grafts file, UTF-16 log encoding, and more)
• test_embedded_bundles.py:
  • listings skip an embedded bundle at any path, but not an ordinary folder
    that has the marker file names
  • init's saved manifest excludes its own bundle
• test_external_links.py:
  • any scheme is external
  • external links are reported and never dangle
• test_manifest_digest.py:
  • the digest covers dirty bytes that a git SHA does not
  • the policy hook lets a snapshot refresh through

scripts/smoke.sh passes against the installed commands.

🤖 Generated with Claude Code

[vsov]

Thank you! This is integrated into the source tree and published in a0517dd ("Unreleased: audit fixes A1-A10 and contributed PRs #4-#8"). Your commits were cherry-picked with authorship kept; this repository is an export of the source, so the PR itself is closed rather than merged. Your tests live in the source tree, which the export does not ship.

Follow-ups: the reference bundle and release fixtures now carry ids (okfy migrate ids); okfy_links golden shape pins external. Note: links() lives in query.py, so the retrieval code digest does move (the index fingerprint does not).

See CHANGELOG.md ## Unreleased for the full entry.