@superbee/core 0.1.0

package/dist/freshness.js

@@ -0,0 +1,98 @@
+/**
+ * Freshness derivation from the document's edition-neutral meaningful-change clock.
+ *
+ * OKF v0.2's `stale_after` supplies an absolute date; v0.1 `timestamp` and v0.2
+ * `generated.at` supply the instant of the last meaningful change. The remaining
+ * staleness rules are consumer judgments layered on top:
+ *   - `empty` — no usable meaningful-change time is present.
+ *   - `stale` — a declared dependency was written more recently than this concept,
+ *               OR the concept's age exceeds `maxAgeMs`.
+ *   - `fresh` — otherwise.
+ * The v0.2 absolute date takes precedence, then dependency-newer, then the age rule.
+ *
+ * Pure and dependency-free, hence directly unit-testable.
+ */
+import { meaningfulChangeTimeValue } from "./meaningful-change-time.js";
+/**
+ * Parse a timestamp to epoch ms, or `null`. Accepts an ISO-8601 (or any
+ * `Date.parse`-able) STRING — the normal case, since {@link parseMarkdown}
+ * normalizes frontmatter dates to strings — and, as belt-and-suspenders, a raw
+ * `Date` or epoch-millis `number` should one reach here unnormalized.
+ */
+export function parseTimestamp(ts) {
+    if (ts instanceof Date) {
+        const ms = ts.getTime();
+        return Number.isNaN(ms) ? null : ms;
+    }
+    if (typeof ts === "number") {
+        return Number.isFinite(ts) ? ts : null;
+    }
+    if (typeof ts !== "string" || ts.trim() === "")
+        return null;
+    const ms = Date.parse(ts);
+    return Number.isNaN(ms) ? null : ms;
+}
+/** Parse a strict ISO date without allowing Date.parse to normalize impossible calendar dates. */
+function dateOnly(value) {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return null;
+    const parsed = new Date(`${value}T00:00:00Z`);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value
+        ? value
+        : null;
+}
+/** The caller's local calendar day; OKF deliberately defines `today` without a UTC override. */
+function localDateOnly(value) {
+    const year = String(value.getFullYear()).padStart(4, "0");
+    const month = String(value.getMonth() + 1).padStart(2, "0");
+    const day = String(value.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+/**
+ * Derive a freshness verdict from `generated.at`, falling back to legacy `timestamp`.
+ *
+ * @param doc     the concept document (v0.2 `stale_after` and meaningful-change clocks are consulted).
+ * @param options bundle edition, `now` (defaults to the current instant), `maxAgeMs`, and
+ *                the ISO timestamps of upstream `dependsOn` artifacts.
+ */
+export function freshness(doc, options = {}) {
+    const tsMs = parseTimestamp(meaningfulChangeTimeValue(doc.frontmatter));
+    const now = options.now ?? new Date();
+    const ageMs = tsMs === null ? undefined : now.getTime() - tsMs;
+    const staleAfter = options.okfVersion === "0.2"
+        ? dateOnly(doc.frontmatter.stale_after)
+        : null;
+    if (staleAfter !== null && localDateOnly(now) >= staleAfter) {
+        return {
+            verdict: "stale",
+            ...(ageMs === undefined ? {} : { ageMs }),
+            reason: `today is on or after stale_after ${staleAfter}`,
+        };
+    }
+    if (tsMs === null) {
+        return { verdict: "empty", reason: "no usable meaningful-change time (`generated.at` or `timestamp`)" };
+    }
+    const meaningfulAgeMs = now.getTime() - tsMs;
+    // Dependency-based staleness wins: any dependency newer than this concept.
+    if (options.dependsOn && options.dependsOn.length > 0) {
+        for (const dep of options.dependsOn) {
+            const depMs = parseTimestamp(dep);
+            if (depMs !== null && depMs > tsMs) {
+                return {
+                    verdict: "stale",
+                    ageMs: meaningfulAgeMs,
+                    reason: `a dependency (${dep}) is newer than this concept`,
+                };
+            }
+        }
+    }
+    if (typeof options.maxAgeMs === "number" && meaningfulAgeMs > options.maxAgeMs) {
+        return {
+            verdict: "stale",
+            ageMs: meaningfulAgeMs,
+            reason: `age ${meaningfulAgeMs}ms exceeds max ${options.maxAgeMs}ms`,
+        };
+    }
+    return { verdict: "fresh", ageMs: meaningfulAgeMs };
+}
+//# sourceMappingURL=freshness.js.map

package/dist/freshness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.js","sourceRoot":"","sources":["../src/freshness.ts"],"names":[],"mappings":"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"}

package/dist/frontmatter-contract.d.ts

@@ -0,0 +1,17 @@
+/** Runtime-neutral error and predicates shared by storage adapters and the engine. */
+/**
+ * A document whose YAML frontmatter could not be parsed. `context` identifies the document when
+ * known; `detail` is the first line of the parser error, and `cause` preserves the original error.
+ */
+export declare class MalformedDocumentError extends Error {
+    readonly name = "MalformedDocumentError";
+    readonly context?: string;
+    readonly detail: string;
+    constructor(context: string | undefined, cause: unknown);
+}
+/**
+ * The engine's usable-document-timestamp predicate: a non-empty (post-trim) string. Anything else
+ * is unusable, and the edition-aware write path replaces it with the current time.
+ */
+export declare function isUsableTimestamp(value: unknown): value is string;
+//# sourceMappingURL=frontmatter-contract.d.ts.map

package/dist/frontmatter-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-contract.d.ts","sourceRoot":"","sources":["../src/frontmatter-contract.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAkB,IAAI,4BAA4B;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO;CAWxD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEjE"}

package/dist/frontmatter-contract.js

@@ -0,0 +1,29 @@
+/** Runtime-neutral error and predicates shared by storage adapters and the engine. */
+/**
+ * A document whose YAML frontmatter could not be parsed. `context` identifies the document when
+ * known; `detail` is the first line of the parser error, and `cause` preserves the original error.
+ */
+export class MalformedDocumentError extends Error {
+    name = "MalformedDocumentError";
+    context;
+    detail;
+    constructor(context, cause) {
+        const detail = ((cause instanceof Error ? cause.message : String(cause)).split("\n")[0] ?? "")
+            .trim();
+        super(`malformed frontmatter${context ? ` in '${context}'` : ""}: ${detail} — ` +
+            `fix the YAML or remove the file`);
+        if (context !== undefined)
+            this.context = context;
+        this.detail = detail;
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+/**
+ * The engine's usable-document-timestamp predicate: a non-empty (post-trim) string. Anything else
+ * is unusable, and the edition-aware write path replaces it with the current time.
+ */
+export function isUsableTimestamp(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+//# sourceMappingURL=frontmatter-contract.js.map

package/dist/frontmatter-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-contract.js","sourceRoot":"","sources":["../src/frontmatter-contract.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF;;;GAGG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC7B,IAAI,GAAG,wBAAwB,CAAC;IACzC,OAAO,CAAU;IACjB,MAAM,CAAS;IAExB,YAAY,OAA2B,EAAE,KAAc;QACrD,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aAC3F,IAAI,EAAE,CAAC;QACV,KAAK,CACH,wBAAwB,OAAO,CAAC,CAAC,CAAC,QAAQ,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,KAAK;YACvE,iCAAiC,CACpC,CAAC;QACF,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAClD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,KAAK,KAAK,SAAS;YAAG,IAA4B,CAAC,KAAK,GAAG,KAAK,CAAC;IACvE,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AAC1D,CAAC"}

package/dist/frontmatter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Markdown + YAML frontmatter (de)serialization via `gray-matter`.
+ *
+ * This is the ONLY module that touches the YAML layer; every other module works
+ * with the already-parsed {@link Frontmatter}/body shapes. gray-matter delimits
+ * frontmatter with `---` lines (OKF §4.1) and preserves unknown keys on
+ * round-trip (OKF v0.1 §9 / v0.2 §11 permissive consumption).
+ */
+import type { Frontmatter } from "./types.js";
+export { isUsableTimestamp, MalformedDocumentError } from "./frontmatter-contract.js";
+/**
+ * Parse raw markdown into `{ frontmatter, body }`. Missing frontmatter yields `{}`. Malformed YAML
+ * throws an attributed {@link MalformedDocumentError} (naming `context` when given).
+ *
+ * Passing parser options bypasses gray-matter's input cache. Without options, gray-matter can cache
+ * a still-unparsed file before YAML parsing, causing a later parse of the same malformed bytes to
+ * return empty data instead of throwing again. The custom YAML engine also preserves timestamp-like
+ * scalars as strings so date-only values retain their original semantic shape.
+ */
+export declare function parseMarkdown(raw: string, context?: string): {
+    frontmatter: Frontmatter;
+    body: string;
+};
+/** Match the exact body shape emitted by the document serializer. */
+export declare function normalizeDocumentBodyForStorage(body: string): string;
+/** Serialize an arbitrary YAML-mapping + body to OKF markdown (used for reserved files). */
+export declare function stringifyWithData(data: Record<string, unknown>, body: string): string;
+/** Serialize a concept document's frontmatter + body to OKF-conformant markdown. */
+export declare function stringifyDoc(frontmatter: Frontmatter, body: string): string;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAmEtF;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,GACf;IAAE,WAAW,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAqB5C;AAED,qEAAqE;AACrE,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,4FAA4F;AAC5F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CASrF;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3E"}

package/dist/frontmatter.js

@@ -0,0 +1,115 @@
+/**
+ * Markdown + YAML frontmatter (de)serialization via `gray-matter`.
+ *
+ * This is the ONLY module that touches the YAML layer; every other module works
+ * with the already-parsed {@link Frontmatter}/body shapes. gray-matter delimits
+ * frontmatter with `---` lines (OKF §4.1) and preserves unknown keys on
+ * round-trip (OKF v0.1 §9 / v0.2 §11 permissive consumption).
+ */
+import matter from "gray-matter";
+import yaml from "js-yaml";
+import { isUsableTimestamp, MalformedDocumentError } from "./frontmatter-contract.js";
+export { isUsableTimestamp, MalformedDocumentError } from "./frontmatter-contract.js";
+const YAML_TIMESTAMP_TAG = "tag:yaml.org,2002:timestamp";
+function requireYamlTimestampType() {
+    const type = yaml.DEFAULT_SAFE_SCHEMA.implicit.find((candidate) => candidate.tag === YAML_TIMESTAMP_TAG);
+    if (!type)
+        throw new Error("js-yaml safe schema is missing its timestamp type");
+    return type;
+}
+const yamlTimestampType = requireYamlTimestampType();
+/**
+ * Keep YAML timestamps as their original strings. The default schema constructs both
+ * `2026-01-02` and `2026-01-02T00:00:00Z` as identical `Date` objects, irreversibly erasing the
+ * date-only distinction before unknown nested frontmatter can be preserved.
+ */
+const stringTimestampType = new yaml.Type(YAML_TIMESTAMP_TAG, {
+    kind: "scalar",
+    resolve: (value) => yamlTimestampType.resolve(value),
+    construct: (value) => value,
+});
+const losslessDateSchema = new yaml.Schema({
+    include: [yaml.DEFAULT_SAFE_SCHEMA],
+    implicit: [stringTimestampType],
+});
+const yamlEngine = {
+    parse(input) {
+        return (yaml.safeLoad(input, { schema: losslessDateSchema }) ?? {});
+    },
+};
+/**
+ * Normalize the legacy top-level `timestamp` field to an ISO-8601 string.
+ *
+ * gray-matter/js-yaml turns an UNQUOTED ISO timestamp scalar — the form OKF's own
+ * sample bundles use (`timestamp: 2026-07-01T12:05:00Z`) — into a non-string under its
+ * default schema. The parser above now retains all YAML timestamp scalars as strings so
+ * date-only values remain distinguishable at any depth. This legacy field still keeps its
+ * established canonical ISO behavior, including epoch-millisecond input.
+ */
+function normalizeFrontmatter(data) {
+    const out = { ...data };
+    const value = out.timestamp;
+    if (value instanceof Date) {
+        out.timestamp = value.toISOString();
+    }
+    else if (typeof value === "number" && Number.isFinite(value)) {
+        out.timestamp = new Date(value).toISOString();
+    }
+    else if (typeof value === "string" && yamlTimestampType.resolve(value)) {
+        const parsed = yamlTimestampType.construct(value);
+        if (parsed instanceof Date)
+            out.timestamp = parsed.toISOString();
+    }
+    return out;
+}
+/**
+ * Parse raw markdown into `{ frontmatter, body }`. Missing frontmatter yields `{}`. Malformed YAML
+ * throws an attributed {@link MalformedDocumentError} (naming `context` when given).
+ *
+ * Passing parser options bypasses gray-matter's input cache. Without options, gray-matter can cache
+ * a still-unparsed file before YAML parsing, causing a later parse of the same malformed bytes to
+ * return empty data instead of throwing again. The custom YAML engine also preserves timestamp-like
+ * scalars as strings so date-only values retain their original semantic shape.
+ */
+export function parseMarkdown(raw, context) {
+    // An exact opening delimiter asserts that the document has YAML frontmatter. gray-matter accepts
+    // a missing closing delimiter when the remaining bytes happen to be valid YAML (Markdown heading
+    // lines are YAML comments), then returns an empty body. That is lossy ambiguity, not a successful
+    // parse: every caller must see the same attributed malformed-document result before it can read,
+    // export, or rewrite a body that silently disappeared.
+    if (/^---(?:\r?\n|$)/.test(raw)) {
+        const firstLineEnd = raw.indexOf("\n");
+        const afterOpening = firstLineEnd === -1 ? "" : raw.slice(firstLineEnd + 1);
+        if (!/^---\r?$/m.test(afterOpening)) {
+            throw new MalformedDocumentError(context, new Error("unterminated YAML frontmatter delimiter"));
+        }
+    }
+    let parsed;
+    try {
+        parsed = matter(raw, { engines: { yaml: yamlEngine } });
+    }
+    catch (err) {
+        throw new MalformedDocumentError(context, err);
+    }
+    const frontmatter = normalizeFrontmatter((parsed.data ?? {}));
+    return { frontmatter, body: parsed.content };
+}
+/** Match the exact body shape emitted by the document serializer. */
+export function normalizeDocumentBodyForStorage(body) {
+    return body.endsWith("\n") ? body : `${body}\n`;
+}
+/** Serialize an arbitrary YAML-mapping + body to OKF markdown (used for reserved files). */
+export function stringifyWithData(data, body) {
+    const engines = matter.engines;
+    const yaml = engines.yaml.stringify(data).trim();
+    const content = body ?? "";
+    const newline = (value) => (value.endsWith("\n") ? value : `${value}\n`);
+    if (yaml === "{}")
+        return normalizeDocumentBodyForStorage(content);
+    return `---\n${newline(yaml)}---\n${normalizeDocumentBodyForStorage(content)}`;
+}
+/** Serialize a concept document's frontmatter + body to OKF-conformant markdown. */
+export function stringifyDoc(frontmatter, body) {
+    return stringifyWithData(frontmatter, body);
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,IAAI,MAAM,SAAS,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGtF,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAEtF,MAAM,kBAAkB,GAAG,6BAA6B,CAAC;AAUzD,SAAS,wBAAwB;IAC/B,MAAM,IAAI,GAAI,IAAI,CAAC,mBAA+C,CAAC,QAAQ,CAAC,IAAI,CAC9E,CAAC,SAAS,EAAE,EAAE,CAAE,SAAwB,CAAC,GAAG,KAAK,kBAAkB,CACpE,CAAC;IACF,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IAChF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,iBAAiB,GAAG,wBAAwB,EAAE,CAAC;AAErD;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE;IAC5D,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC;IACpD,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK;CAC5B,CAAC,CAAC;AAEH,MAAM,kBAAkB,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC;IACzC,OAAO,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC;IACnC,QAAQ,EAAE,CAAC,mBAAmB,CAAC;CAChC,CAAC,CAAC;AAEH,MAAM,UAAU,GAAG;IACjB,KAAK,CAAC,KAAa;QACjB,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC,IAAI,EAAE,CAAW,CAAC;IAChF,CAAC;CACF,CAAC;AAEF;;;;;;;;GAQG;AACH,SAAS,oBAAoB,CAAC,IAA6B;IACzD,MAAM,GAAG,GAA4B,EAAE,GAAG,IAAI,EAAE,CAAC;IACjD,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,CAAC;IAC5B,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1B,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACtC,CAAC;SAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IAChD,CAAC;SAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzE,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAClD,IAAI,MAAM,YAAY,IAAI;YAAE,GAAG,CAAC,SAAS,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACnE,CAAC;IACD,OAAO,GAAkB,CAAC;AAC5B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAW,EACX,OAAgB;IAEhB,iGAAiG;IACjG,iGAAiG;IACjG,kGAAkG;IAClG,iGAAiG;IACjG,uDAAuD;IACvD,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,YAAY,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;QAC5E,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,sBAAsB,CAAC,OAAO,EAAE,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC,CAAC;QAClG,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;IAC1D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,sBAAsB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,WAAW,GAAG,oBAAoB,CAAC,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAA4B,CAAC,CAAC;IACzF,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;AAC/C,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,+BAA+B,CAAC,IAAY;IAC1D,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC;AAClD,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,iBAAiB,CAAC,IAA6B,EAAE,IAAY;IAC3E,MAAM,OAAO,GAAI,MAEf,CAAC,OAAO,CAAC;IACX,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACjD,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;IACzF,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACnE,OAAO,QAAQ,OAAO,CAAC,IAAI,CAAC,QAAQ,+BAA+B,CAAC,OAAO,CAAC,EAAE,CAAC;AACjF,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,YAAY,CAAC,WAAwB,EAAE,IAAY;IACjE,OAAO,iBAAiB,CAAC,WAAsC,EAAE,IAAI,CAAC,CAAC;AACzE,CAAC"}

package/dist/index-marker.d.ts

@@ -0,0 +1,3 @@
+/** Whole-body ownership marker for AgentState-generated portable indexes. */
+export declare const GENERATED_INDEX_MARKER = "<!-- agentstate-lite:generated-index:v1 -->";
+//# sourceMappingURL=index-marker.d.ts.map

package/dist/index-marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-marker.d.ts","sourceRoot":"","sources":["../src/index-marker.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,gDAAgD,CAAC"}

package/dist/index-marker.js

@@ -0,0 +1,3 @@
+/** Whole-body ownership marker for AgentState-generated portable indexes. */
+export const GENERATED_INDEX_MARKER = "<!-- agentstate-lite:generated-index:v1 -->";
+//# sourceMappingURL=index-marker.js.map

package/dist/index-marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-marker.js","sourceRoot":"","sources":["../src/index-marker.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,sBAAsB,GAAG,6CAA6C,CAAC"}

package/dist/index-projection.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Portable `index.md` projection policy.
+ *
+ * Concept heads are authoritative. Index files are deterministic, replaceable views over
+ * one observed head set. Planning is pure; preparation reads and classifies EVERY target
+ * before a write; application uses those exact versions with single-shot CAS. A conflict
+ * stops the batch instead of silently re-deciding one file outside the global preflight.
+ */
+import type { Bundle, HeadResult, Version } from "./types.js";
+export { GENERATED_INDEX_MARKER } from "./index-marker.js";
+/** One directory's deterministic, frontmatter-free body. `dir === ""` is the bundle root. */
+export interface PlannedIndex {
+    dir: string;
+    body: string;
+}
+/** A complete recursive projection over one observed set of concept heads. */
+export interface IndexProjectionPlan {
+    targets: PlannedIndex[];
+}
+export type IndexProjectionDisposition = "missing" | "generated" | "unchanged" | "adopted" | "refused";
+/** One target after reading its current bytes and classifying ownership. */
+export interface PreparedIndexTarget {
+    dir: string;
+    content: string;
+    expectedVersion: Version | null;
+    disposition: IndexProjectionDisposition;
+    reason?: "unmarked" | "malformed-marker" | "duplicate-marker" | "nested-frontmatter" | "malformed-root";
+}
+export interface ReadyIndexProjection {
+    ready: true;
+    targets: PreparedIndexTarget[];
+    refused: [];
+}
+export interface RefusedIndexProjection {
+    ready: false;
+    targets: PreparedIndexTarget[];
+    refused: PreparedIndexTarget[];
+}
+/** Preparation is the dry-run/check result the future CLI can project directly. */
+export type IndexProjectionPreparation = ReadyIndexProjection | RefusedIndexProjection;
+export interface AppliedIndexTarget {
+    dir: string;
+    disposition: Exclude<IndexProjectionDisposition, "unchanged" | "refused">;
+    version: Version;
+}
+export interface IndexProjectionApplyResult {
+    completed: AppliedIndexTarget[];
+    unchanged: string[];
+    pending: [];
+}
+/** A terminal per-file failure after zero or more earlier targets completed. */
+export declare class IndexProjectionWriteError extends Error {
+    readonly name = "IndexProjectionWriteError";
+    readonly failed: string;
+    readonly completed: AppliedIndexTarget[];
+    readonly pending: string[];
+    constructor(failed: string, completed: AppliedIndexTarget[], pending: string[], cause: unknown);
+}
+/**
+ * Plan root + every ancestor directory from ONE complete `queryHeads`-shaped set.
+ * The caller supplies the root display name; core never derives it from a local path or URL.
+ */
+export declare function planIndexProjection(displayName: string, heads: readonly HeadResult[]): IndexProjectionPlan;
+/**
+ * Read and classify every planned target before any write. A single refusal blocks the
+ * whole preparation; `force` makes each unmarked/malformed target an explicit adoption.
+ */
+export declare function prepareIndexProjection(bundle: Bundle, plan: IndexProjectionPlan, options?: {
+    force?: boolean;
+}): Promise<IndexProjectionPreparation>;
+/**
+ * Apply a ready preparation deepest-first and root-last. Each target gets ONE CAS attempt
+ * against the version captured during global preparation; a conflict is terminal and reports
+ * completed/pending paths so a full re-prepare can resume idempotently.
+ */
+export declare function applyIndexProjection(bundle: Bundle, prepared: ReadyIndexProjection, options?: {
+    actor?: string;
+}): Promise<IndexProjectionApplyResult>;
+//# sourceMappingURL=index-projection.d.ts.map

package/dist/index-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-projection.d.ts","sourceRoot":"","sources":["../src/index-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,6FAA6F;AAC7F,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,MAAM,0BAA0B,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEvG,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE,0BAA0B,CAAC;IACxC,MAAM,CAAC,EAAE,UAAU,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,oBAAoB,GAAG,gBAAgB,CAAC;CACzG;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,OAAO,EAAE,EAAE,CAAC;CACb;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAED,mFAAmF;AACnF,MAAM,MAAM,0BAA0B,GAAG,oBAAoB,GAAG,sBAAsB,CAAC;AAEvF,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC,0BAA0B,EAAE,WAAW,GAAG,SAAS,CAAC,CAAC;IAC1E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,EAAE,CAAC;CACb;AAED,gFAAgF;AAChF,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,SAAkB,IAAI,+BAA+B;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,kBAAkB,EAAE,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;gBAGzB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,kBAAkB,EAAE,EAC/B,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,OAAO;CAOjB;AA8CD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,mBAAmB,CAsD1G;AAsDD;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,mBAAmB,EACzB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,0BAA0B,CAAC,CAgDrC;AAQD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CAkCrC"}