@equationalapplications/core-okf 5.3.0 → 5.4.0

package/README.md

@@ -4,11 +4,11 @@
 
 ## Overview
 
-A zero-dependency library for parsing and producing [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) bundles. This package provides the raw primitives to work with OKF frontmatter, concept documents, and index/log files, completely decoupled from any specific database or data model.
+A zero-dependency library for parsing and producing [Open Knowledge Format (OKF) v0.1 and v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) bundles. This package provides the raw primitives to work with OKF frontmatter, concept documents, and index/log files, completely decoupled from any specific database or data model.
 
 For a ready-made `MemoryDump` ⇄ OKF bundle adapter, see the [OKF Import/Export section in `@equationalapplications/core-llm-wiki`](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core/README.md#okf-importexport).
 
-For the llm-wiki interoperability profile (llm-wiki/1), see [`docs/okf-profile.md`](https://github.com/equationalapplications/expo-llm-wiki/blob/main/docs/okf-profile.md). Conformance fixtures live in [`fixtures/`](./fixtures/).
+For the llm-wiki interoperability profiles (`llm-wiki/1` and `llm-wiki/2`), see [`docs/okf-profile.md`](https://github.com/equationalapplications/expo-llm-wiki/blob/main/docs/okf-profile.md). Conformance fixtures live in [`fixtures/`](./fixtures/).
 
 ## Installation
 
@@ -75,3 +75,15 @@ const links = extractMarkdownLinks('See [preferences](facts/fact_abc.md) for mor
 | [@equationalapplications/core-llm-tools](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core-llm-tools/README.md) | Gemini tool schemas and capability injector |
 | [**@equationalapplications/core-okf**](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/okf/README.md) | Zero-dependency Open Knowledge Format (OKF) v0.1 primitives — parse and produce interoperable knowledge bundles. |
 | [@equationalapplications/schema-org-llm-wiki](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/schema-org/README.md) | Curated schema.org warm-agent ontology manifest |
+
+## OKF v0.2 conformance
+
+This package conforms to [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md). New helpers for v0.2:
+
+- `deriveTrustTier(verified)` — derive `'unverified' | 'machine-confirmed' | 'human-reviewed'`.
+- `isStaleAfter(staleAfter, now)` — staleness check against an absolute `YYYY-MM-DD` cutoff.
+- `parseVerifiedFlexible(value)` — accept either an array or a bare `{ by, at }` mapping.
+- `extractFootnotes(body)` / `serializeFootnotes(footnotes)` — preserve footnote attribution verbatim.
+- `parseFlowMapping(text)` / `parseFlowSequence(text)` — flow parsing with at most one level of mapping-value nesting (no anchors/aliases outside quoted strings).
+
+The `serializeFrontmatter` function emits plain objects as flow mappings and actor strings (containing `/` or `:`) via `serializeActorString`. Anchor/alias expansion is rejected; only **unquoted** `&` or `*` characters are treated as opaque (quoted spans are excluded from the scan, so URL query strings like `"https://x/a?p=1&q=2"` remain valid).

package/dist/index.d.mts

@@ -1,5 +1,7 @@
 type OkfFrontmatterScalar = string | number | boolean | null;
-type OkfFrontmatterValue = OkfFrontmatterScalar | OkfFrontmatterScalar[];
+type OkfFrontmatterValue = OkfFrontmatterScalar | OkfFrontmatterScalar[] | {
+    [key: string]: OkfFrontmatterValue | undefined;
+} | OkfFrontmatterValue[];
 interface OkfFrontmatter {
     type: string;
     title?: string;
@@ -30,8 +32,54 @@ interface OkfMarkdownLink {
     text: string;
     path: string;
 }
+type OkfStatus = 'draft' | 'stable' | 'deprecated';
+type OkfActorKind = 'agent' | 'human' | 'process';
+interface OkfGenerated {
+    by: string;
+    at: string;
+}
+interface OkfVerifiedEntry {
+    by: string;
+    at: string;
+    [key: string]: OkfFrontmatterScalar;
+}
+type OkfVerified = OkfVerifiedEntry[];
+interface OkfSourceUsageWindow {
+    from: string;
+    to: string;
+    [key: string]: OkfFrontmatterScalar;
+}
+interface OkfSource {
+    id?: string;
+    resource: string;
+    title?: string;
+    author?: string;
+    usage_count?: number;
+    last_modified?: string;
+    usage_window?: OkfSourceUsageWindow;
+    [key: string]: OkfFrontmatterValue | undefined;
+}
+interface OkfFootnote {
+    id: string;
+    body: string;
+}
 
+declare function serializeActorString(value: string): string;
 declare function serializeFrontmatter(fm: OkfFrontmatter): string;
+/**
+ * `depth` counts levels of **mapping-value nesting** only: it increments when a
+ * flow MAPPING's key has a value that is itself a flow collection, and is
+ * rejected once it would exceed 1 (spec §2.6's "at most one level of nesting").
+ * It does NOT increment when a flow SEQUENCE's item is itself a mapping or
+ * sequence — `sources: [ {...}, {...} ]` (a flat array of objects) is the base
+ * shape v0.2 uses everywhere and is not "nesting" in the spec's sense. This is
+ * what lets `sources: [ { usage_window: { from, to } } ]` parse (sequence item
+ * is a mapping at depth 0; that mapping's `usage_window` value is a mapping at
+ * depth 1 — one level, allowed) while `{ a: { b: { c: 1 } } }` is rejected
+ * (`a`'s value nests at depth 1; `b`'s value would need depth 2 — rejected).
+ */
+declare function parseFlowMapping(text: string, depth?: number): Record<string, OkfFrontmatterValue> | null;
+declare function parseFlowSequence(text: string, depth?: number): OkfFrontmatterValue[] | null;
 /**
  * Parses the subset of YAML frontmatter that {@link serializeFrontmatter} produces:
  * scalar string/number/boolean/null values, quoted strings, and block string-lists.
@@ -105,4 +153,31 @@ declare function isAllowedOkfPath(filePath: string): boolean;
  */
 declare function extractMarkdownLinks(body: string): OkfMarkdownLink[];
 
-export { type OkfFile, type OkfFrontmatter, type OkfFrontmatterScalar, type OkfFrontmatterValue, type OkfIndexEntry, type OkfIndexSection, type OkfLogEntry, type OkfMarkdownLink, appendEventIdComment, appendRelatedSection, buildConceptDocument, buildEntityIndexMd, buildIndexMd, buildLogMd, buildRootIndexMd, extractMarkdownLinks, isAllowedOkfPath, parseConcept, parseEntityIndexMd, parseEventIdComment, parseFrontmatter, parseLogMd, parseRootIndexMd, serializeFrontmatter, splitRelatedSection };
+/**
+ * Extracts footnote definitions from a body. OKF v0.2 footnote attribution uses
+ * `[^id]` markers whose label joins to `sources[].id`. This helper parses the
+ * `[^id]: text` definition lines at the body tail and returns them as opaque
+ * text — we deliberately do NOT try to interpret which body span uses which
+ * footnote; the body is the source of truth and is preserved verbatim on
+ * round-trip.
+ */
+declare function extractFootnotes(body: string): OkfFootnote[];
+/** Joins footnote definitions back into a body block. Continuation lines are
+ * indented (two spaces) so that {@link extractFootnotes} — which only
+ * recognizes continuation lines that are indented per CommonMark — round-trips
+ * multi-line bodies. */
+declare function serializeFootnotes(footnotes: OkfFootnote[]): string;
+
+type TrustTier = 'unverified' | 'machine-confirmed' | 'human-reviewed';
+declare function deriveTrustTier(verified: OkfVerified | undefined): TrustTier;
+declare function isStaleAfter(staleAfter: string | number | null, now: number): boolean;
+declare function parseVerifiedFlexible(value: unknown): OkfVerified;
+declare function formatVerifiedJson(entries: OkfVerified): string;
+declare function formatSourcesJson(sources: OkfSource[], sharedWindow?: OkfSourceUsageWindow | null): string;
+declare function latestVerified(entries: OkfVerified | undefined, _now: number): {
+    by: string;
+    at: number;
+} | null;
+declare function parseCitationsList(body: string): string[];
+
+export { type OkfActorKind, type OkfFile, type OkfFootnote, type OkfFrontmatter, type OkfFrontmatterScalar, type OkfFrontmatterValue, type OkfGenerated, type OkfIndexEntry, type OkfIndexSection, type OkfLogEntry, type OkfMarkdownLink, type OkfSource, type OkfSourceUsageWindow, type OkfStatus, type OkfVerified, type OkfVerifiedEntry, type TrustTier, appendEventIdComment, appendRelatedSection, buildConceptDocument, buildEntityIndexMd, buildIndexMd, buildLogMd, buildRootIndexMd, deriveTrustTier, extractFootnotes, extractMarkdownLinks, formatSourcesJson, formatVerifiedJson, isAllowedOkfPath, isStaleAfter, latestVerified, parseCitationsList, parseConcept, parseEntityIndexMd, parseEventIdComment, parseFlowMapping, parseFlowSequence, parseFrontmatter, parseLogMd, parseRootIndexMd, parseVerifiedFlexible, serializeActorString, serializeFootnotes, serializeFrontmatter, splitRelatedSection };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 type OkfFrontmatterScalar = string | number | boolean | null;
-type OkfFrontmatterValue = OkfFrontmatterScalar | OkfFrontmatterScalar[];
+type OkfFrontmatterValue = OkfFrontmatterScalar | OkfFrontmatterScalar[] | {
+    [key: string]: OkfFrontmatterValue | undefined;
+} | OkfFrontmatterValue[];
 interface OkfFrontmatter {
     type: string;
     title?: string;
@@ -30,8 +32,54 @@ interface OkfMarkdownLink {
     text: string;
     path: string;
 }
+type OkfStatus = 'draft' | 'stable' | 'deprecated';
+type OkfActorKind = 'agent' | 'human' | 'process';
+interface OkfGenerated {
+    by: string;
+    at: string;
+}
+interface OkfVerifiedEntry {
+    by: string;
+    at: string;
+    [key: string]: OkfFrontmatterScalar;
+}
+type OkfVerified = OkfVerifiedEntry[];
+interface OkfSourceUsageWindow {
+    from: string;
+    to: string;
+    [key: string]: OkfFrontmatterScalar;
+}
+interface OkfSource {
+    id?: string;
+    resource: string;
+    title?: string;
+    author?: string;
+    usage_count?: number;
+    last_modified?: string;
+    usage_window?: OkfSourceUsageWindow;
+    [key: string]: OkfFrontmatterValue | undefined;
+}
+interface OkfFootnote {
+    id: string;
+    body: string;
+}
 
+declare function serializeActorString(value: string): string;
 declare function serializeFrontmatter(fm: OkfFrontmatter): string;
+/**
+ * `depth` counts levels of **mapping-value nesting** only: it increments when a
+ * flow MAPPING's key has a value that is itself a flow collection, and is
+ * rejected once it would exceed 1 (spec §2.6's "at most one level of nesting").
+ * It does NOT increment when a flow SEQUENCE's item is itself a mapping or
+ * sequence — `sources: [ {...}, {...} ]` (a flat array of objects) is the base
+ * shape v0.2 uses everywhere and is not "nesting" in the spec's sense. This is
+ * what lets `sources: [ { usage_window: { from, to } } ]` parse (sequence item
+ * is a mapping at depth 0; that mapping's `usage_window` value is a mapping at
+ * depth 1 — one level, allowed) while `{ a: { b: { c: 1 } } }` is rejected
+ * (`a`'s value nests at depth 1; `b`'s value would need depth 2 — rejected).
+ */
+declare function parseFlowMapping(text: string, depth?: number): Record<string, OkfFrontmatterValue> | null;
+declare function parseFlowSequence(text: string, depth?: number): OkfFrontmatterValue[] | null;
 /**
  * Parses the subset of YAML frontmatter that {@link serializeFrontmatter} produces:
  * scalar string/number/boolean/null values, quoted strings, and block string-lists.
@@ -105,4 +153,31 @@ declare function isAllowedOkfPath(filePath: string): boolean;
  */
 declare function extractMarkdownLinks(body: string): OkfMarkdownLink[];
 
-export { type OkfFile, type OkfFrontmatter, type OkfFrontmatterScalar, type OkfFrontmatterValue, type OkfIndexEntry, type OkfIndexSection, type OkfLogEntry, type OkfMarkdownLink, appendEventIdComment, appendRelatedSection, buildConceptDocument, buildEntityIndexMd, buildIndexMd, buildLogMd, buildRootIndexMd, extractMarkdownLinks, isAllowedOkfPath, parseConcept, parseEntityIndexMd, parseEventIdComment, parseFrontmatter, parseLogMd, parseRootIndexMd, serializeFrontmatter, splitRelatedSection };
+/**
+ * Extracts footnote definitions from a body. OKF v0.2 footnote attribution uses
+ * `[^id]` markers whose label joins to `sources[].id`. This helper parses the
+ * `[^id]: text` definition lines at the body tail and returns them as opaque
+ * text — we deliberately do NOT try to interpret which body span uses which
+ * footnote; the body is the source of truth and is preserved verbatim on
+ * round-trip.
+ */
+declare function extractFootnotes(body: string): OkfFootnote[];
+/** Joins footnote definitions back into a body block. Continuation lines are
+ * indented (two spaces) so that {@link extractFootnotes} — which only
+ * recognizes continuation lines that are indented per CommonMark — round-trips
+ * multi-line bodies. */
+declare function serializeFootnotes(footnotes: OkfFootnote[]): string;
+
+type TrustTier = 'unverified' | 'machine-confirmed' | 'human-reviewed';
+declare function deriveTrustTier(verified: OkfVerified | undefined): TrustTier;
+declare function isStaleAfter(staleAfter: string | number | null, now: number): boolean;
+declare function parseVerifiedFlexible(value: unknown): OkfVerified;
+declare function formatVerifiedJson(entries: OkfVerified): string;
+declare function formatSourcesJson(sources: OkfSource[], sharedWindow?: OkfSourceUsageWindow | null): string;
+declare function latestVerified(entries: OkfVerified | undefined, _now: number): {
+    by: string;
+    at: number;
+} | null;
+declare function parseCitationsList(body: string): string[];
+
+export { type OkfActorKind, type OkfFile, type OkfFootnote, type OkfFrontmatter, type OkfFrontmatterScalar, type OkfFrontmatterValue, type OkfGenerated, type OkfIndexEntry, type OkfIndexSection, type OkfLogEntry, type OkfMarkdownLink, type OkfSource, type OkfSourceUsageWindow, type OkfStatus, type OkfVerified, type OkfVerifiedEntry, type TrustTier, appendEventIdComment, appendRelatedSection, buildConceptDocument, buildEntityIndexMd, buildIndexMd, buildLogMd, buildRootIndexMd, deriveTrustTier, extractFootnotes, extractMarkdownLinks, formatSourcesJson, formatVerifiedJson, isAllowedOkfPath, isStaleAfter, latestVerified, parseCitationsList, parseConcept, parseEntityIndexMd, parseEventIdComment, parseFlowMapping, parseFlowSequence, parseFrontmatter, parseLogMd, parseRootIndexMd, parseVerifiedFlexible, serializeActorString, serializeFootnotes, serializeFrontmatter, splitRelatedSection };

package/dist/index.js

@@ -26,6 +26,10 @@ function quoteString(value) {
 function serializeScalarString(value) {
   return needsQuoting(value) ? quoteString(value) : value;
 }
+function serializeActorString(value) {
+  if (/[/:]/.test(value)) return quoteString(value);
+  return value;
+}
 function serializeKey(key) {
   if (/\s/.test(key) || needsQuoting(key) || isIso8601Timestamp(key)) {
     return quoteString(key);
@@ -37,8 +41,52 @@ function serializeValue(value) {
   if (typeof value === "boolean") return String(value);
   if (typeof value === "number") return String(value);
   if (typeof value === "string") return serializeScalarString(value);
+  if (Array.isArray(value)) return serializeFlowSequenceValue(value);
+  if (typeof value === "object") return serializeFlowMappingValue(value);
   throw new Error(`Unsupported frontmatter value type: ${typeof value}`);
 }
+function needsFlowQuoting(value) {
+  return needsQuoting(value) || /[,{}[\]/:]/.test(value);
+}
+function serializeFlowScalarString(value) {
+  return needsFlowQuoting(value) ? quoteString(value) : value;
+}
+function serializeFlowMappingValue(obj, depth = 0) {
+  const entries = Object.entries(obj).filter(([, v]) => v !== void 0);
+  if (entries.length === 0) return "{}";
+  const parts = entries.map(([k, v]) => {
+    let rendered;
+    if (typeof v === "string") rendered = serializeFlowScalarString(v);
+    else if (v === null || typeof v === "boolean" || typeof v === "number") rendered = serializeValue(v);
+    else if (Array.isArray(v)) {
+      if (depth >= 1) throw new Error(`serializeFlowMappingValue: nesting deeper than one level is not supported (key "${k}")`);
+      rendered = serializeFlowSequenceValue(v, depth + 1);
+    } else if (typeof v === "object") {
+      if (depth >= 1) throw new Error(`serializeFlowMappingValue: nesting deeper than one level is not supported (key "${k}")`);
+      rendered = serializeFlowMappingValue(v, depth + 1);
+    } else {
+      throw new Error(`serializeFlowMappingValue: unsupported value type for key "${k}"`);
+    }
+    return `${serializeKey(k)}: ${rendered}`;
+  });
+  return `{ ${parts.join(", ")} }`;
+}
+function serializeFlowSequenceValue(arr, depth = 0) {
+  if (arr.length === 0) return "[]";
+  const parts = arr.map((item) => {
+    if (typeof item === "string") return serializeFlowScalarString(item);
+    if (item === null || typeof item === "boolean" || typeof item === "number") return serializeValue(item);
+    if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+      return serializeFlowMappingValue(item, depth);
+    }
+    if (Array.isArray(item)) {
+      if (depth >= 1) throw new Error(`serializeFlowSequenceValue: nested array deeper than one level is not supported`);
+      return serializeFlowSequenceValue(item, depth + 1);
+    }
+    throw new Error("serializeFlowSequenceValue: unsupported item type");
+  });
+  return `[ ${parts.join(", ")} ]`;
+}
 function serializeFrontmatter(fm) {
   const lines = ["---"];
   for (const [key, value] of Object.entries(fm)) {
@@ -46,16 +94,16 @@ function serializeFrontmatter(fm) {
     if (Array.isArray(value)) {
       if (value.length === 0) {
         lines.push(`${serializeKey(key)}: []`);
+      } else if (value.some((item) => item !== null && typeof item === "object")) {
+        lines.push(`${serializeKey(key)}: ${serializeFlowSequenceValue(value)}`);
       } else {
         lines.push(`${serializeKey(key)}:`);
         for (const item of value) {
-          if (typeof item === "string") {
-            lines.push(`  - ${serializeScalarString(item)}`);
-          } else {
-            lines.push(`  - ${serializeValue(item)}`);
-          }
+          lines.push(`  - ${typeof item === "string" ? serializeScalarString(item) : serializeValue(item)}`);
         }
       }
+    } else if (value !== null && typeof value === "object") {
+      lines.push(`${serializeKey(key)}: ${serializeFlowMappingValue(value)}`);
     } else {
       lines.push(`${serializeKey(key)}: ${serializeValue(value)}`);
     }
@@ -134,6 +182,121 @@ function matchFrontmatterKeyValue(line) {
   const tail = line.slice(key.length + 1);
   return { key, value: tail.trimStart(), hasValue: tail.trim().length > 0 };
 }
+function hasUnquotedAnchorOrAlias(text) {
+  let quote = null;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === "\\" && i + 1 < text.length) {
+        i++;
+        continue;
+      }
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "&" || ch === "*") return true;
+  }
+  return false;
+}
+function splitFlowEntries(inner) {
+  const entries = [];
+  let buf = "";
+  let i = 0;
+  let quote = null;
+  let depthBrace = 0;
+  let depthBracket = 0;
+  while (i < inner.length) {
+    const ch = inner[i];
+    if (quote) {
+      buf += ch;
+      if (ch === "\\" && i + 1 < inner.length) {
+        buf += inner[i + 1];
+        i += 2;
+        continue;
+      }
+      if (ch === quote) quote = null;
+      i++;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      buf += ch;
+      i++;
+      continue;
+    }
+    if (ch === "{") depthBrace++;
+    else if (ch === "}") depthBrace--;
+    else if (ch === "[") depthBracket++;
+    else if (ch === "]") depthBracket--;
+    if (ch === "," && depthBrace === 0 && depthBracket === 0) {
+      entries.push(buf.trim());
+      buf = "";
+      i++;
+      continue;
+    }
+    buf += ch;
+    i++;
+  }
+  if (buf.trim().length > 0) entries.push(buf.trim());
+  if (depthBrace !== 0 || depthBracket !== 0 || quote !== null) return null;
+  return entries;
+}
+function parseFlowMapping(text, depth = 0) {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return null;
+  if (hasUnquotedAnchorOrAlias(trimmed)) return null;
+  const inner = trimmed.slice(1, -1).trim();
+  if (inner.length === 0) return {};
+  const entries = splitFlowEntries(inner);
+  if (!entries) return null;
+  const out = {};
+  for (const entry of entries) {
+    const kv = matchFrontmatterKeyValue(entry);
+    if (!kv || !kv.hasValue) return null;
+    const v = kv.value.trim();
+    if (v.startsWith("{") || v.startsWith("[")) {
+      if (depth >= 1) return null;
+      const nested = v.startsWith("{") ? parseFlowMapping(v, depth + 1) : parseFlowSequence(v, depth + 1);
+      if (nested === null) return null;
+      out[parseKey(kv.key)] = nested;
+      continue;
+    }
+    out[parseKey(kv.key)] = parseScalarValue(v);
+  }
+  return out;
+}
+function parseFlowSequence(text, depth = 0) {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return null;
+  if (hasUnquotedAnchorOrAlias(trimmed)) return null;
+  const inner = trimmed.slice(1, -1).trim();
+  if (inner.length === 0) return [];
+  const entries = splitFlowEntries(inner);
+  if (!entries) return null;
+  const out = [];
+  for (const entry of entries) {
+    const v = entry.trim();
+    if (v.startsWith("{")) {
+      const nested = parseFlowMapping(v, depth);
+      if (nested === null) return null;
+      out.push(nested);
+      continue;
+    }
+    if (v.startsWith("[")) {
+      if (depth >= 1) return null;
+      const nested = parseFlowSequence(v, depth + 1);
+      if (nested === null) return null;
+      out.push(nested);
+      continue;
+    }
+    out.push(parseScalarValue(v));
+  }
+  return out;
+}
 function parseFrontmatter(content) {
   const lines = content.split(/\r?\n/);
   const fallback = { frontmatter: { type: "" }, rest: content };
@@ -171,6 +334,34 @@ function parseFrontmatter(content) {
       frontmatter[key] = items;
       continue;
     }
+    const valueRaw = kv.value.trim();
+    if (valueRaw.startsWith("{")) {
+      const flowObj = parseFlowMapping(valueRaw);
+      if (flowObj !== null) {
+        frontmatter[parseKey(kv.key)] = flowObj;
+        i++;
+        continue;
+      }
+      frontmatter[parseKey(kv.key)] = null;
+      i++;
+      continue;
+    }
+    if (valueRaw.startsWith("[")) {
+      if (valueRaw === "[]") {
+        frontmatter[parseKey(kv.key)] = [];
+        i++;
+        continue;
+      }
+      const flowSeq = parseFlowSequence(valueRaw);
+      if (flowSeq !== null) {
+        frontmatter[parseKey(kv.key)] = flowSeq;
+        i++;
+        continue;
+      }
+      frontmatter[parseKey(kv.key)] = null;
+      i++;
+      continue;
+    }
     frontmatter[parseKey(kv.key)] = parseScalarValue(kv.value);
     i++;
   }
@@ -427,6 +618,181 @@ function extractMarkdownLinks(body) {
   return links;
 }
 
+// src/footnotes.ts
+var FOOTNOTE_DEFINITION = /^\[\^([^\]]+)\]:\s?(.*)$/;
+function extractFootnotes(body) {
+  const out = [];
+  const lines = body.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    const m = FOOTNOTE_DEFINITION.exec(lines[i]);
+    if (!m) {
+      i++;
+      continue;
+    }
+    const id = m[1];
+    const firstLine = m[2] ?? "";
+    const collected = [firstLine];
+    i++;
+    while (i < lines.length) {
+      const next = lines[i];
+      if (FOOTNOTE_DEFINITION.test(next)) break;
+      if (/^\s{2,}\S/.test(next) || /^\s{2,}/.test(next)) {
+        collected.push(next.replace(/^\s{2}/, ""));
+        i++;
+        continue;
+      }
+      break;
+    }
+    out.push({ id, body: collected.join("\n").trimEnd() });
+  }
+  return out;
+}
+function serializeFootnotes(footnotes) {
+  return footnotes.map((f) => {
+    const lines = f.body.split("\n");
+    const [firstLine, ...continuation] = lines;
+    const tail = continuation.map((line) => `
+  ${line}`).join("");
+    return `[^${f.id}]: ${firstLine ?? ""}${tail}`;
+  }).join("\n");
+}
+
+// src/v02-helpers.ts
+function deriveTrustTier(verified) {
+  if (!verified || verified.length === 0) return "unverified";
+  for (const v of verified) {
+    if (typeof v?.by === "string" && v.by.startsWith("human:")) return "human-reviewed";
+  }
+  return "machine-confirmed";
+}
+function parseStaleAfter(staleAfter) {
+  if (staleAfter == null) return null;
+  if (typeof staleAfter === "number") return Number.isFinite(staleAfter) ? staleAfter : null;
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(staleAfter);
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const ts = Date.UTC(year, month - 1, day);
+  if (!Number.isFinite(ts)) return null;
+  const d = new Date(ts);
+  if (d.getUTCFullYear() !== year || d.getUTCMonth() + 1 !== month || d.getUTCDate() !== day) {
+    return null;
+  }
+  return ts;
+}
+function isStaleAfter(staleAfter, now) {
+  const cutoff = parseStaleAfter(staleAfter);
+  if (cutoff == null) return false;
+  return now >= cutoff;
+}
+function parseVerifiedFlexible(value) {
+  if (value == null) return [];
+  if (Array.isArray(value)) {
+    return value.filter(
+      (v) => !!v && typeof v === "object" && typeof v.by === "string" && typeof v.at === "string"
+    );
+  }
+  if (typeof value === "object" && typeof value.by === "string" && typeof value.at === "string") {
+    return [value];
+  }
+  return [];
+}
+function formatVerifiedJson(entries) {
+  const sorted = [...entries].sort((a, b) => {
+    const ta = Date.parse(a.at);
+    const tb = Date.parse(b.at);
+    const fa = Number.isFinite(ta);
+    const fb = Number.isFinite(tb);
+    if (fa && fb) return ta - tb;
+    if (fa && !fb) return -1;
+    if (!fa && fb) return 1;
+    return a.at < b.at ? -1 : a.at > b.at ? 1 : 0;
+  });
+  return JSON.stringify(sorted);
+}
+function formatSourcesJson(sources, sharedWindow) {
+  const folded = sources.map(
+    (s) => s.usage_window ? s : sharedWindow ? { ...s, usage_window: sharedWindow } : s
+  );
+  return JSON.stringify(folded);
+}
+function latestVerified(entries, _now) {
+  if (!entries || entries.length === 0) return null;
+  let best = null;
+  let bestAt = -Infinity;
+  for (const e of entries) {
+    const ts = Date.parse(e.at);
+    if (Number.isFinite(ts) && ts > bestAt) {
+      best = e;
+      bestAt = ts;
+    }
+  }
+  if (!best) return null;
+  return { by: best.by, at: bestAt };
+}
+var URL_LINE = /^\s*-\s+(https?:\/\/\S+)\s*$/;
+function parseCitationsList(body) {
+  const lines = body.split(/\r?\n/);
+  let inFence = false;
+  let fenceMarker = "";
+  let fenceLength = 0;
+  let startIdx = -1;
+  const isFenceClose = (marker, fullMatch, line) => {
+    if (marker[0] !== fenceMarker) return false;
+    if (marker.length < fenceLength) return false;
+    return /^\s*$/.test(line.slice(fullMatch.length));
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fence = /^\s*(```+|~~~+)/.exec(line);
+    if (fence) {
+      const marker = fence[1];
+      if (!inFence) {
+        inFence = true;
+        fenceMarker = marker[0];
+        fenceLength = marker.length;
+      } else if (isFenceClose(marker, fence[0], line)) {
+        inFence = false;
+        fenceMarker = "";
+        fenceLength = 0;
+      }
+      continue;
+    }
+    if (!inFence && /^\s*#{1,2}\s*citations\s*$/i.test(line)) {
+      startIdx = i;
+      break;
+    }
+  }
+  if (startIdx === -1) return [];
+  const out = [];
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    const fence = /^\s*(```+|~~~+)/.exec(line);
+    if (fence) {
+      const marker = fence[1];
+      if (!inFence) {
+        inFence = true;
+        fenceMarker = marker[0];
+        fenceLength = marker.length;
+        continue;
+      }
+      if (isFenceClose(marker, fence[0], line)) {
+        inFence = false;
+        fenceMarker = "";
+        fenceLength = 0;
+      }
+      continue;
+    }
+    if (!inFence && /^\s*#{1,2}\s+/.test(line)) break;
+    if (inFence) continue;
+    const m = URL_LINE.exec(line);
+    if (m) out.push(m[1]);
+  }
+  return out;
+}
+
 exports.appendEventIdComment = appendEventIdComment;
 exports.appendRelatedSection = appendRelatedSection;
 exports.buildConceptDocument = buildConceptDocument;
@@ -434,14 +800,26 @@ exports.buildEntityIndexMd = buildEntityIndexMd;
 exports.buildIndexMd = buildIndexMd;
 exports.buildLogMd = buildLogMd;
 exports.buildRootIndexMd = buildRootIndexMd;
+exports.deriveTrustTier = deriveTrustTier;
+exports.extractFootnotes = extractFootnotes;
 exports.extractMarkdownLinks = extractMarkdownLinks;
+exports.formatSourcesJson = formatSourcesJson;
+exports.formatVerifiedJson = formatVerifiedJson;
 exports.isAllowedOkfPath = isAllowedOkfPath;
+exports.isStaleAfter = isStaleAfter;
+exports.latestVerified = latestVerified;
+exports.parseCitationsList = parseCitationsList;
 exports.parseConcept = parseConcept;
 exports.parseEntityIndexMd = parseEntityIndexMd;
 exports.parseEventIdComment = parseEventIdComment;
+exports.parseFlowMapping = parseFlowMapping;
+exports.parseFlowSequence = parseFlowSequence;
 exports.parseFrontmatter = parseFrontmatter;
 exports.parseLogMd = parseLogMd;
 exports.parseRootIndexMd = parseRootIndexMd;
+exports.parseVerifiedFlexible = parseVerifiedFlexible;
+exports.serializeActorString = serializeActorString;
+exports.serializeFootnotes = serializeFootnotes;
 exports.serializeFrontmatter = serializeFrontmatter;
 exports.splitRelatedSection = splitRelatedSection;
 //# sourceMappingURL=index.js.map