llm-ingestion-okf/docs/plan/okf-v0.2-alignment.md

# OKF v0.2 alignment — plan

Status: **decisions open, no code approved.** This is a policy track, not a
roadmap phase: it decides how the library relates to upstream OKF v0.2 and where
each decision is owned. Everything built so far targets v0.1.

Read with: `docs/plan/execution-order.md` (where this track sits in the
sequence), `docs/plan/phase-3-configurable-contract.md` (the profile object that
carries the outcome), `docs/phase-3-split-table.md` (the profile/guard/consumer
column discipline this track reuses).

## Provenance of the facts below

Read from `GoogleCloudPlatform/knowledge-catalog`, `okf/SPEC.md` at **`main` on
2026-07-26** — a branch, not a tag. **First step of any implementation is to
re-read the spec at a pinned commit and record it**, exactly as assumption C2
pins the proving consumer's validator to `9ee5a8e`. An enumeration read off a
moving branch is a premise, not a fact.

## What v0.2 actually changes

Two supersessions — the only backward-breaking changes, and both carry a
documented consumer fallback (§13.1):

| v0.1 | v0.2 | Fallback the spec grants |
|---|---|---|
| `timestamp` | `generated.at` | Consumers **MAY** fall back to legacy `timestamp` **when `generated` is absent** |
| body `# Citations` list | `sources` frontmatter | Consumers **SHOULD** read `sources`, **MAY** still parse legacy `# Citations` |

Additive, all optional (§5): `sources` (per-source credibility signals —
`author`, `usage_count`, `last_modified`, framed by `usage_window`), `generated
{ by, at }`, `verified [ { by, at } ]`, `status` (`draft`/`stable`/`deprecated`,
absent means `stable`), `stale_after` (absolute `YYYY-MM-DD`).

Also new:

- **Actor convention (§7).** `<producer>/<version>` for an agent or tool,
  `human:<id>`, `process:<id>`. Consumers that classify trust key off the
  `human:` prefix, so producers **MUST** use it for hand-authored or
  human-confirmed content. Trust tiers (unverified / machine-confirmed /
  human-reviewed) are *derived* advisory signals, never a stored field.
- **`Attested Computation`** concept type, with `runtime`, `parameters`,
  `computation`, `executor`, `attester`. The receipt and verdict wire formats and
  the full runtime protocol are **explicitly deferred to a future revision**.
- **`okf_version`** stays root-`index.md`-only and is a **MAY**: a declaration of
  the version a bundle *targets*, with no conformance checkpoint tying the
  declaration to compliance.
- **Consumer tolerance is unchanged and broad.** A consumer MUST NOT reject a
  bundle for missing optional fields, unknown `type` values, unknown frontmatter
  keys, broken cross-links, or missing `index.md`. One additional MUST: a bare
  `verified` mapping must be read as a one-element list.

One YAML detail that decides the parser scope: the canonical form for `generated`
and a single `verified` is an **inline flow mapping** on one line
(`generated: { by: …, at: … }`). Only a multi-verifier `verified` and `sources`
are block lists.

## Exposure audit — measured against the tree, not reasoned

| Surface | Status under v0.2 | Decision owner |
|---|---|---|
| `DEFAULT` emits `generated: "true"` (`materialize.py:164`, `inbox.py:127`) | **Malformed for a v0.2 field**: `generated.by` is REQUIRED within `generated`. `generated` was *not* reserved in v0.1, so this was legal when written — v0.2 claimed the name | **commons** (ingest-spec §5) |
| `_is_ingest_owned` requires `generated == "true"` (`materialize.py:143-149`) | **Fail-safe.** A v0.2 mapping is not the string `"true"`, so the predicate returns False → target not ours → collision → refuse to overwrite. No safety hole | this repo |
| `STRICT_V1` emits `timestamp`, and **no** `generated` | **Conformant** via the §13.1 legacy fallback, which applies precisely *because* `generated` is absent. No action is forced on the wiki | wiki |
| `parse_frontmatter` is scalar-only (`partition(":")` → `dict[str, str]`) | Reads an inline flow mapping as an **opaque string** — round-trip-safe. Cannot read block lists, so `sources` and multi-verifier `verified` are unreachable | this repo |
| Fixtures and tests pin `okf_version: 0.1` | Accurate today: a MAY-field target declaration | **catalog** (decision E1: `okf_version` tracks the upstream Google version) |
| catalog's gate checks `okf_version` on **form** (`/^\d+(\.\d+)*$/`), not membership | `"0.2"` passes unchanged — an upstream bump breaks no gate | catalog |

Two results worth stating plainly, because both cut against the first reading:

1. **`STRICT_V1`'s `timestamp` is not broken.** It sits on the documented legacy
   path. The earlier framing of it as a required-field defect was wrong.
2. **`DEFAULT` is the only surface with a real shape problem**, and it is the one
   surface this repo may not unilaterally change: `DEFAULT` states the
   ingest-spec §5 layer, whose authorship is commons'. Patching it locally is an
   existing non-goal.

Note the interaction that makes (1) conditional: the `timestamp` fallback is
granted only when `generated` is **absent**. Any profile that emits both a
`timestamp` and a malformed `generated` would have neither a valid `generated.at`
nor an eligible fallback. No current profile does this — `DEFAULT` has no
`timestamp` and `STRICT_V1` has no `generated` — and no profile should be allowed
to reach that combination.

## The sequencing rule we impose on ourselves

**Conform first, claim after.** Do not move a bundle's `okf_version` to `"0.2"`
before the bundle's shape satisfies what it claims.

The spec does not require this — §12 is a MAY with no conformance checkpoint
attached, so declaring `"0.2"` early would be permitted. We adopt the rule
anyway, for the same reason as *measure first, widen after* on the guard pin: a
version claim that is literally permitted but not earned is the true-sounding
misleading claim, and that class of mistake has already cost this repo a session.

## Open questions — to answer before any code

Numbered like the phase-3 assumptions so they can be cited in review.

**V1 — Does `generated` change shape in `DEFAULT`, and may it?**
This is the central question and the answer is *not ours alone*: `DEFAULT` is
commons' §5 layer. Three directions to put to commons, with our recommendation:

- (a) Leave `generated: "true"`; document the deviation. Cheapest; keeps emitting
  a v0.2 field with a v1-era value.
- (b) **Recommended.** Migrate to
  `generated: { by: "llm-ingestion-okf/<version>", at: <ingested_at> }` and
  derive the machine-generated predicate from `generated.by` instead of a bespoke
  boolean. This is the spec-native answer, removes a hand-rolled key, and yields
  a real `generated.at`. `at` binds to the already-validated required
  `ingested_at` argument, so no wall-clock default is introduced and determinism
  holds. Costs: a `_is_ingest_owned` change and a golden-fixture regeneration.
- (c) Rename our marker to a non-reserved key and leave `generated` free for v0.2
  semantics. Preserves the predicate exactly; still a fixture regeneration.

**V2 — How far does the frontmatter parser need to go?**
Two tiers, and only the first is cheap:

- Tier 1, inline flow mappings: already round-trip as opaque strings. This needs
  a **characterization test**, not a change.
- Tier 2, block lists (`sources`, multi-verifier `verified`): real work.

The question is whether any named consumer requires Tier 2 today. If none does,
Tier 2 stays an extension point — the inverse of *fields without a reader are not
written*: do not build a parser for a field no profile reads.

**V3 — Do we add v0.2 trust fields to any profile at all?**
Default answer **no**, until a named consumer asks. Neither wiki nor catalog has.
`status`, `stale_after`, `verified`, and `sources` are all optional upstream, and
adding them speculatively is the speculative-abstraction anti-pattern that
phase 3 exists to avoid.

**V4 — What value does `okf_version` carry, and who sets it?**
Already recorded as policy-not-constant. E1 gives the decision to catalog. This
repo's obligation is narrower and testable: no profile may hard-code `0.1`, and
the root-frontmatter policy must express any value.

**V5 — Is `Attested Computation` in scope?**
Recommended **out**, on two independent grounds. Upstream has deferred the
receipt and verdict wire formats, so building now means porting an unfrozen
contract — the precise failure mode `execution-order.md` warns about for the Node
half. And attestation ("did this run produce the value the sanctioned way") sits
against the guard's boundary rather than this library's plumbing, so the boundary
question goes to the operator before any design.

## TDD order — when quota returns

Steps 1–3 are characterization and audit only: they add tests, change no
behavior, and are safe to run before V1 is answered.

1. **Characterize what already holds.** `parse_frontmatter` round-trips an inline
   flow mapping opaquely; `_is_ingest_owned` returns False for a v0.2 `generated`
   mapping. The second test converts today's fail-safe from an accident into a
   documented guarantee.
2. **Audit Door C against the tolerance rules** — one test per consumer MUST NOT
   (unknown `type`, unknown key, broken cross-link, missing `index.md`) plus the
   bare-`verified`-as-one-element-list MUST. Measured, not reasoned: Door C is a
   consumer in the OKF sense and either honours these or does not.
3. **Assert no hard-coded `0.1`** anywhere a profile should decide (V4).
4. **Only after commons answers V1:** the `generated` migration, its
   `_is_ingest_owned` change, and the golden-fixture regeneration — as its own
   release with its own CHANGELOG entry, never folded into another change.

## Key assumptions, each with its test

| # | Assumption | Test |
|---|---|---|
| V-A1 | The spec enumeration above is complete | Re-read `okf/SPEC.md` at a **pinned commit**, record the commit, diff against this doc before step 4 |
| V-A2 | Inline flow mappings survive our parser unmodified | Step 1 characterization test; byte-exact round-trip |
| V-A3 | v0.2 input cannot cause an unowned overwrite | Step 1 test: `_is_ingest_owned` False on a `generated` mapping |
| V-A4 | Door C meets the v0.2 consumer tolerance rules | Step 2, one test per MUST NOT — a failure here is a real defect, not a plan revision |
| V-A5 | No profile hard-codes an upstream version | Step 3 |
| V-A6 | The `generated` migration is byte-neutral outside frontmatter | Golden diff confined to the frontmatter block; every other byte identical |

## Non-goals

- Implementing `Attested Computation`, executors, attesters, receipts, or
  verdicts (V5).
- Adding any optional v0.2 family to a profile without a named consumer
  requesting it (V3).
- Editing commons' ingest-spec locally. V1 is raised in commons; if commons
  declines, the deviation is documented rather than patched here.
- Moving `okf_version` to `"0.2"` in any fixture or profile before the shape
  earns it, and never without catalog.
- Any change to the wiki's `timestamp`. It is on the documented legacy path;
  the wiki is informed, not asked.

## Coordination — who needs to know what

Notification set, not an approval queue. Each entry names the one thing that
repo owns:

- **commons** — V1. The only blocking dependency: `generated`'s shape in the
  ingest-spec §5 layer.
- **catalog** — form owner. That upstream moved to v0.2, that its form-not-
  membership gate absorbs the bump with no change, and that V4 is theirs.
- **wiki** — informational. Their `timestamp` is legacy-but-readable under
  §13.1; no action is required of them, and the earlier reading that called it a
  defect was wrong.
- **okr** — before the reference-implementation lift, so the Node half is not
  ported against a v0.1-shaped contract.

## Verification

1. Spec re-read at a pinned commit; commit hash recorded in this doc.
2. `pytest` green; `mypy --strict src/`; `ruff check .` and
   `ruff format --check .` clean.
3. Steps 1–3 add tests and change zero production behavior: golden suite
   byte-for-byte, `git diff --stat examples/` empty.
4. V1 answered in writing by commons before step 4 begins.
5. If step 4 lands: golden diff confined to the frontmatter block; boundary
   grep-gate still empty; its own release and CHANGELOG entry.