llm-ingestion-okf/docs/plan/okf-2026-08-timestamp-tightening.md

# Upstream OKF round, 2026-08-23 — the timestamp tightening, and the repository move

Runbook run of `docs/upstream-okf-upgrade-runbook.md`, executed 2026-08-23 on an
operator GO. Previous round: `docs/plan/okf-v0.2-alignment.md` (v0.1 → v0.2, pinned
`3fcbb9f`).

This round found two things the runbook was not shaped for, and both matter more
than the change that triggered it:

1. **OKF moved to its own repository.** The tree we had pinned is now a declared
   frozen snapshot. The runbook's Trigger step pointed at it by name.
2. **The spec changed without a version bump.** `SPEC.md` still says Version 0.2.
   Step 4's classification vocabulary had no bucket for that.

The triggering change itself — every timestamp becomes an ISO 8601 datetime with an
explicit offset — costs this library nothing. That conclusion is measured, not
assumed; the denominators are below.

---

## Step 1 — Pins

Everything below was read at a fixed commit, never at a branch.

| What | Commit | Date | Role |
|---|---|---|---|
| `GoogleCloudPlatform/open-knowledge-format` | `ad30107c31c06aec8a7d5636e0d1058118604e6f` | 2026-08-21 | **New canonical source.** Read at this pin |
| `GoogleCloudPlatform/knowledge-catalog` | `395a0c311979858dcecfed767810658baf3ca3f3` | 2026-08-22 | Frozen `okf/` snapshot, read for divergence |
| `GoogleCloudPlatform/knowledge-catalog` | `3fcbb9f828c2f23d109c855ee403c3a4c81f3a96` | 2026-07-24 | **Our current pin**, the v0.2-round baseline |

The order that authorized this run named `62432a09` as the target. That commit is
real (`okf: make every timestamp an ISO 8601 datetime with an explicit offset
(#323)`, 2026-08-20) but it is a commit in the *frozen* tree, and it was not the
head of anything by the time this ran. Verified before use rather than adopted:
`knowledge-catalog` had advanced 53 commits past our pin, and the canonical tree is
a different repository.

Local read-only mirrors: `~/repos/_okf-upstream` (knowledge-catalog, pre-existing)
and `~/repos/_okf-canonical` (new, cloned this round, push URL disabled).

## Step 2 — Enumeration, with denominators

**Canonical repo at `ad30107`: 132 tracked files.**

| Top level | Files |
|---|---|
| `bundles/` | 83 (acme_retail 19, crypto_bitcoin 16, ga4 15, stackoverflow 33) |
| `src/` | 27 |
| `tests/` | 8 |
| `samples/` | 6 |
| `connectors/` | 1 — **new**, not present in the tree we had pinned |
| root files | 7 (`SPEC.md`, `README.md`, `pyproject.toml`, `LICENSE.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `.gitignore`) |

By extension: 89 `md`, 31 `py`, 5 `html`, 3 `txt`, 1 each of `toml`, `js`, `css`,
`gitignore`.

Of the 53 `knowledge-catalog` commits between our pin and its current head, **3
touched `okf/`**. The other 50 are `toolbox/` work (`mdcode`, `enrichment`) and are
out of scope for this library — stated with the denominator, not as an impression.

## Step 3 — The move, read from the primary source

`6265173 okf: point readers at the dedicated OKF repository (#324)` adds a notice to
`okf/README.md`:

> **OKF now lives in its own repository:
> GoogleCloudPlatform/open-knowledge-format.** … **Stop using the copy under `okf/`
> in this repository.** It is a frozen snapshot, no longer maintained, and anything
> built against it will drift out of date.

This is the finding with the longest reach. "Always latest" is a promise about a
tree, and the tree changed identity. The runbook's Trigger step — *Check
`GoogleCloudPlatform/knowledge-catalog`, path `okf/`* — would have kept sending
future rounds at a snapshot that upstream says will drift, and each such round would
have reported "no change" truthfully and uselessly.

### The two trees have already diverged

The canonical repo does **not** carry `38c713f okf: write stackoverflow bundle tags
as YAML lists (#293)` (2026-08-14), which is present in the snapshot it declares
obsolete. Measured across the 8 affected files, each differing by exactly the `tags:`
line and nothing else:

```
canonical:  tags: stackoverflow, posts, questions      # one plain scalar
frozen kc:  tags: [stackoverflow, posts, questions]    # a sequence
```

Upstream's own commit message for that fix records what the scalar form cost them: a
JavaScript string is iterable, so each one expanded into one label *per character*.
The canonical repository currently ships the form upstream had already diagnosed as
corrupting.

We are not exposed: this library neither writes nor reads OKF `tags` (measured — one
occurrence of the substring across 11 modules, in `extract.py:86`, about HTML tags).
Door C is exposed only in the sense that it merges external concepts **verbatim** by
design, so a consumer importing the canonical `stackoverflow` bundle would carry the
scalar form through unchanged. That is the verbatim invariant working, not a defect.

## Step 4 — The diff, classified

Between our pin `3fcbb9f:okf/` (129 files) and canonical `ad30107` (132 files), every
`.py` file differs by a 14-line Apache licence header added at the move. Confirmed as
an artifact rather than assumed: stripping those 14 lines makes the files byte-
identical. Excluding it, the substantive set is small.

**Normative (`SPEC.md`), 22 changed lines, all one change.** Every timestamp-valued
key becomes an ISO 8601 datetime with an explicit UTC offset. New sentence in §5:

> Every timestamp-valued key in OKF is an ISO 8601 datetime with an explicit UTC
> offset, for example `2026-06-30T14:00:00Z`.

Three keys change form; the rest of the diff is the examples and prose following
them:

| Key | Was | Is |
|---|---|---|
| `stale_after` (§5.5) | `YYYY-MM-DD` | datetime with offset |
| `sources[].last_modified` (§5.1) | `YYYY-MM-DD` | datetime with offset |
| `usage_window.{from,to}` (§5.1) | date range | datetime range |

`generated.at` and `verified.at` were already datetimes with `Z` and are untouched.

**Not a version bump.** `SPEC.md` still declares Version 0.2, and §12's minor/major
rules are unchanged. This is a *tightening of the normative text in place*: a value
that conformed on 2026-07-24 does not conform now, under the same version number. The
runbook's Step 4 vocabulary (Breaking / Additive / Deferred upstream / Observed but
undocumented) has no bucket for it, which is why it is named here as a fifth class —
**tightened in place, no version bump** — and why declaring conformance to "v0.2"
without also naming a commit is now ambiguous. Our `okf_spec_commit` key already
anticipated this; this round is the first time it earns its keep.

**Reference reader (`src/reference_agent/bundle/document.py`), 34 substantive
lines, two behaviour changes.**

*Change 1 — a date-only `stale_after` is now silently ignored.* `is_stale` returns
`False` for any value without a `T`, on the stated reasoning that a date-only value
"names a different instant in every timezone, so it is ignored rather than guessed
at". Measured on identical input at both pins, with `now` set 17 months past the
date:

| `stale_after` | reader @ `3fcbb9f` | reader @ `ad30107` |
|---|---|---|
| `2026-12-31` | `is_stale=True` | **`is_stale=False`** |
| `2026-12-31T00:00:00Z` | `True` | `True` |
| `2026-12-31T00:00:00+00:00` | — | `True` |

This is the class the black-box promise explicitly cannot absorb. No library change
makes an already-authored date-only `stale_after` mean what its author meant; it now
reads as *never stale* rather than as *stale*, which fails open. Nothing in this
library emits `stale_after`, so our first-order exposure is zero — but any consumer
who authored one has content whose meaning reversed without their file changing.

*Change 2 — timestamps now survive a parse as the text the author wrote.* Upstream
subclasses `SafeLoader` and drops the `tag:yaml.org,2002:timestamp` implicit
resolver, because PyYAML implements YAML 1.1 and was rewriting frontmatter on a
round-trip. Measured against our own golden, same bytes, both pins:

| Key | type @ `3fcbb9f` | type @ `ad30107` |
|---|---|---|
| `ingested_at` | `datetime` | **`str`** (`'2026-07-16T12:00:00Z'`) |
| `generated.at` | `datetime` | **`str`** |
| `okf_version` | `float` (`0.2`) | `float` (`0.2`) — unchanged |

This is a change in our favour: the value an upstream consumer recovers from our
bundle is now the literal we wrote. It also narrows the A-E6 finding — the float
coercion on `okf_version` survives, so that one is still real and still upstream's.

**Additive:** `connectors/gcp-knowledge-catalog.md` (new file), `CONTRIBUTING.md` and
`CODE_OF_CONDUCT.md` (repository furniture that came with the move).

**Deferred upstream (unchanged):** §12 still defers the receipt and verdict wire
formats, the attester ABI, attestation caching, and semantic-layer templates. Our
`Attested Computation` support stays format-only on upstream's deferral, not on our
preference.

**Observed but undocumented:** none this round.

## Step 3a — V-A8, upstream's reader against our fixtures

Run with `/usr/local/bin/python3` (3.14.0, PyYAML 6.0.3) against the pinned clone.
The `.venv` was not touched and nothing was installed; the one-runtime-dependency
rule and its packaging test are intact.

| Bundle | `.md` files | parsed | parse failures |
|---|---|---|---|
| our `ingest-golden-file` | 3 | 3 | 0 |
| our `ingest-golden-http` | 2 | 2 | 0 |
| our `ingest-golden-okf-v0-2` | 2 | 2 | 0 |
| our `ingest-golden-sql` | 2 | 2 | 0 |
| upstream `acme_retail` | 17 | 17 | 0 |
| upstream `crypto_bitcoin` | 15 | 15 | 0 |
| upstream `ga4` | 14 | 14 | 0 |
| upstream `stackoverflow` | 32 | 32 | 0 |

**9 of 9 of our own bundle documents parse under the new reader**, and
`trust_tier`, `normalize_verified` and `is_stale` run over each without raising.

A clean sweep is a weak result unless the harness is shown to be able to fail, so it
was put to a known-positive: a document with `type: [unclosed` raises
`OKFDocumentError` as expected, while a well-formed control parses. The zeroes above
are measurements, not the absence of one.

Two notes on what V-A8 does *not* buy, both carried forward from the v0.2 round:

- `validate()` checks `REQUIRED_FRONTMATTER_KEYS = ("type",)` — one key. It fails on
  our root `index.md`, correctly: an index is not a concept and carries no `type` by
  §12. The runbook's recorded "13/13" counted concept documents; this run's harness
  asserted `validate()` on index files too and so reports one expected failure per
  bundle root. Not a regression — a stricter harness. Do not read the two counts as
  comparable.
- Upstream's `serialize()` still reflows inline flow forms to block form. Unchanged,
  one-directional, and still not a reason to emit block form (D4).

## Step 5 — Exposure

### Ours: measured zero

Every timestamp-valued byte this library emits, across all four golden bundles —
denominator 10 of 10, every one already conformant:

```
examples/ingest-golden-file/expected-bundle/ingest-orders.md:5     ingested_at: 2026-07-16T12:00:00Z
examples/ingest-golden-file/expected-bundle/ingest-orders.md:7     generated: { by: process:okf-ingest, at: 2026-07-16T12:00:00Z }
... 4 further bundles, same two keys, same form
```

The gate is `materialize.py:37`,
`_INGESTED_AT_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$")`, enforced by
`validate_ingested_at` (`materialize.py:49`) and called on every Door A run
(`materialize.py:386`). `generated.at` derives from the same validated value via
`profile.ownership.stamp(ingested_at)` (`materialize.py:235`), so both keys are
covered by one check. The spec's own example of an explicit UTC offset is `Z`, so
this form conforms as written.

The three keys the tightening actually changes are not written by any door:

- `stale_after` is **named but not written** — `profiles.py:757` places it in
  `_OKF_V0_2_KEY_ORDER` so a caller can emit it in canonical order and the schema can
  judge a document carrying one. The comment at `profiles.py:736` says so directly:
  *"Naming a family is not writing it … Door A writes none of them."*
- `last_modified`, `usage_window`, `usage_count` are not emitted at all.
  `materialize.py:188` records the decision: a manifest source has no `author` and no
  `last_modified`, *"and inventing them would be writing fields with no reader."*

Nothing in this library validates a timestamp value other than `ingested_at`
(measured across 11 modules; the query was validated against a known-positive control
before its empty result was believed).

One test fixture carries a now-non-conformant literal:
`tests/test_okf_v0_2_characterization.py:188` uses `stale_after: 2027-01-01` inside a
§14 *consumer-tolerance* case — a document a conformant consumer MUST NOT reject.
That is still exactly what it tests, and the date-only form arguably tests it better
now. **No change proposed.** Flagged so a later reader does not "fix" it.

### Consumers: framed for them to measure, not decided for them

The list was re-derived against disk rather than trusted from the runbook, and all
eight are present (two were initially recorded as absent from a guessed path — a
wrong-path negative, corrected before use):

`portfolio-optimiser-commons`, `portfolio-optimiser`, `portfolio-optimiser-claude`,
`claude-code-llm-wiki`, `catalog`, `okr`, `linkedin-studio`, `ms-ai-architect`.

What has to be true for the tightening to reach a consumer — one falsifiable question
each, for them to run against their real data:

1. **Do you author `stale_after`, `last_modified`, or `usage_window` anywhere?** If
   no, your exposure is zero and this round costs you nothing. If yes, and the value
   is date-only, an OKF v0.2 reader at the current spec now reads it as *never stale*
   rather than as *stale*. It fails open, and it is silent.
2. **Do you declare conformance as "v0.2" without naming a commit?** That string no
   longer identifies one document. Naming the commit alongside it is the fix.
3. **Do you read OKF from `GoogleCloudPlatform/knowledge-catalog`, path `okf/`?**
   That copy is frozen by upstream's own notice, and has already diverged.

Nothing here asserts which consumers are affected. The v0.2 round showed the
falsifiable framing is what made the answers useful.

## Step 6 — The plan

**No new profile.** Support is additive by rule, but there is nothing additive to
express: the spec did not bump, the three tightened keys are ones we do not write,
and what we do write already conforms. Inventing an `OKF_V0_2_1` profile would
declare a version upstream has not minted. *Conform first, claim after.*

**Deliverables, in order:**

1. **Correct the runbook's Trigger step** to name
   `GoogleCloudPlatform/open-knowledge-format` as canonical, record that
   `knowledge-catalog/okf/` is frozen and already divergent, and add the fifth
   diff class (*tightened in place, no version bump*) to Step 4. Done this round —
   leaving a known-false instruction in the procedure would send the next run at a
   dead tree.
2. **Move the pin** `3fcbb9f` → `ad30107`, and with it the repository. Cost, measured:
   **zero bytes in our fixtures.** `okf_spec_commit` is a key the `STRICT_V1` profile
   requires (`profiles.py:721,726`); its *value* is the caller's under D5, and no
   shipped fixture carries one. The cost lands where D5 says it should — on the
   caller that stamps it, as a re-run. This is a separate decision and is **not taken
   here**, per the order.
3. **Re-record V-A8 at the new pin** in `docs/plan/okf-v0.2-alignment.md`'s
   verification table, which currently reads *"DONE 2026-07-31 @ `3fcbb9f`: 13/13"*.
   Pending the pin decision, so the two move together.
4. **Notify consumers** (Step 7) with the three questions above. Not sent this
   round — the order scoped this to analysis and a plan document, and notification
   is a sent action.

**No pilot, no GA event.** Pilot-first governs a *new upstream version* reaching a
new profile. There is no new version and no new profile, so `OKF_LATEST` does not
move and there is nothing to flip. Saying this explicitly because the standing
policy's machinery is easy to run out of habit.

**Guard seam:** nothing in this round touches it. The tightening is a value-format
question inside frontmatter we already gate; the persist gates are unchanged, and the
standing posture that everything entering a bundle passes the guard is unaffected.
Noted, not built.

## Step 8 — Verification log

Every claim above and the command class that produced it. Corrections stay visible.

| Claim | How verified |
|---|---|
| OKF moved; `okf/` is frozen | `git show 6265173` — primary source, upstream's own notice text |
| Canonical pin `ad30107`, 132 files | `git log -1`, `git ls-files \| wc -l` at the pin |
| 3 of 53 kc commits touched `okf/` | `git log --oneline 3fcbb9f..origin/main -- okf` |
| `.py` diffs are a licence header | Stripped 14 lines, files byte-identical (`diff` empty) |
| Spec change is timestamps only | `diff -u` of the two `SPEC.md` files, whole diff read |
| Still Version 0.2, no bump | `SPEC.md:3`, §12 read in full at the new pin |
| Canonical lacks `38c713f` | `diff -rq` frozen-vs-canonical; 8 files, each 2 lines, all `tags:` |
| We never write `tags` | `grep` across 11 modules — 1 unrelated hit (`extract.py:86`) |
| `is_stale` reversal | Same input run against both pinned readers, `now=2027-06-01` |
| `ingested_at` type change | V-A8 type dump, same golden bytes, both pins |
| Our exposure is 10/10 conformant | Frontmatter scan over all 10 `examples/**/*.md` |
| No other timestamp validation | `grep` over 11 modules, **validated against a known-positive control first** |
| `okf_spec_commit` has no fixture value | `grep examples/` exit 1, after `git grep` confirmed the key exists in 3 tracked places |
| V-A8 harness can detect failure | Deliberate `type: [unclosed` → `OKFDocumentError`; control parses |
| All 8 consumers present | `find ~/repos -maxdepth 3 -type d -name <n>`, with a known-positive control |
| Suite green | `.venv/bin/python -m pytest -q` → 596 passed |

**Corrections made during this run, kept visible:**

- The order named `62432a09` as the target. It is a commit in the frozen tree, not
  the canonical head. Verified before it was used as a premise.
- `linkedin-studio` and `ms-ai-architect` were first recorded as absent, from a
  guessed path (`~/repos/<name>`). A wider search found both under
  `~/repos/ktg-plugin-marketplace/`. A negative from a guessed path is not a
  measurement.
- An early `grep … | head; echo $?` reported the exit status of `head`, not of
  `grep` — a negative that measured nothing. Re-run with the status of the actual
  query before its empty result was used.