Skip to content

feat(export): OKF re-export honesty — reproduce foreign frontmatter#102

Merged
ethanj merged 6 commits into
mainfrom
feat/okf-reexport
Jun 14, 2026
Merged

feat(export): OKF re-export honesty — reproduce foreign frontmatter#102
ethanj merged 6 commits into
mainfrom
feat/okf-reexport

Conversation

@ethanj

@ethanj ethanj commented Jun 14, 2026

Copy link
Copy Markdown
Contributor

What

Completes the OKF round-trip so that a page imported from a foreign bundle re-exports honestly rather than as a generic concept.

Import captures an imported document's original frontmatter under an x-okf snapshot (an unknown type such as BigQuery Table maps to kind: concept while the raw type and any producer-specific keys are preserved). Until now nothing read that snapshot back, so re-export emitted type: concept and dropped foreign keys. This wires the snapshot through and re-exports with the right contract:

  • ExportPage carries an optional xOkf snapshot; collect reads the x-okf block back from page frontmatter.
  • On re-export of a page that has a snapshot, mapPageToOkfFrontmatter:
    • preserves the raw foreign type and any unknown producer keys (e.g. vendorKey);
    • derives the OKF standard fields (title, description, tags, timestamp) from the current page, so local edits after import are reflected rather than publishing stale snapshot values;
    • refreshes the x-llmwiki provenance block (content hash, page directory, provenance) from the current page;
    • does not emit x-okf into the exported OKF doc (it stays a llmwiki-side record).
  • Native pages (no snapshot) map exactly as before.
  • The original bundle path is persisted durably under x-okf.okfPath at import, so a page's origin survives review approval and is surfaced by collectExportPages (previously it lived only on the review candidate and was lost once approved).

Why

A foreign bundle should survive import→export honestly — preserving the producer's own type and keys while still reflecting any local edits and layering llmwiki's own provenance. This lets llmwiki act as a faithful pass-through for third-party OKF content.

Scope / known limitation

Re-export places every document at <pageDirectory>/<slug>.md — the llmwiki slug is the identity the OKF link rewriter and index TOC understand (/concepts|queries/<slug>.md). A foreign tables/customers.md therefore re-exports as concepts/tables-customers.md; its original path is preserved durably under x-okf.okfPath for diagnosis. Faithful reconstruction of nested original bundle paths is intentionally deferred — it requires extending the slug-based link/index model.

Test plan

  • npx tsc --noEmit, npm run build, npm test (1619 passed), npx fallow (0 above threshold), dupes clean
  • Unknown foreign type + producer key survive import→export
  • Editing an imported page's title/summary before re-export publishes the current values while still preserving type: BigQuery Table + vendorKey
  • x-okf does not leak into exported OKF frontmatter
  • okfPath persists on the live page across real review approve and is surfaced by export
  • Citation idempotence: export→import→export yields exactly one regenerated # Citations
  • Native pages (no snapshot) map unchanged

@ethanj ethanj merged commit 3e91eec into main Jun 14, 2026
3 checks passed
@ethanj ethanj deleted the feat/okf-reexport branch June 14, 2026 23:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant