@davidorex/pi-context 0.26.0

package/dist/schema-write.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Canonical schema-write surface — read / write / mutate the JSON Schemas
+ * that live alongside project blocks under `<contextDir>/schemas/`.
+ *
+ * Closes structurally:
+ *   - FGAP-011 (canonical schema-write surface): every schema mutation that
+ *     would otherwise reach `.project/schemas/*.schema.json` via direct fs
+ *     edits now has a single typed entry point. Direct fs writes remain
+ *     possible but are now a parallel ungated path that should be retired
+ *     in any future schema mutation per the F-006-bypass-pattern discipline.
+ *
+ * Contract:
+ *   - All schemas pass through AJV draft-07 meta-schema validation before
+ *     they touch disk. Malformed schemas throw `ValidationError` with the
+ *     meta-violation details; the file is not created or modified.
+ *   - Atomic on-disk semantics — writes go to a `<file>.schema-write-<pid>.tmp`
+ *     sibling and are renamed into place. A failed write leaves the prior
+ *     schema byte-identical.
+ *   - Schema files land at `<resolveContextDir(cwd)>/schemas/<schemaName>.schema.json`,
+ *     routed through `schemaPath` (context-dir) so write resolution is identical
+ *     to read resolution — pointer-canonical, `config.root` is NOT a path input
+ *     (FGAP-079 / DEC-0045). Previously based on a config.root-honoring
+ *     path-builder, which diverged from the pointer-canonical read side.
+ *
+ * Out-of-scope for step 3:
+ *   - Schema $id + version + $ref + migration registry (FGAP-006, step 4)
+ *   - Schema diff / change-log tooling
+ *   - Cross-package opinionated mutators (e.g. add-author-fields shorthand)
+ */
+import type { DispatchContext } from "./dispatch-context.js";
+import { ValidationError } from "./schema-validator.js";
+/**
+ * Read a schema from `<contextDir>/schemas/<schemaName>.schema.json` and
+ * return the parsed object. Returns `null` when the file does not exist —
+ * absence is a normal pre-write state, not an error. Throws when the file
+ * exists but is unreadable or contains invalid JSON.
+ *
+ * Note: this reader does NOT meta-validate. Callers that need a guarantee
+ * the file holds a valid schema should pipe the result through
+ * `validateSchemaAgainstMeta` themselves; `updateSchema` already does.
+ */
+export declare function readSchema(cwd: string, schemaName: string): object | null;
+/**
+ * Atomically write `schema` to `<contextDir>/schemas/<schemaName>.schema.json`
+ * after validating it against the JSON Schema draft-07 meta-schema.
+ *
+ * Failure modes:
+ *   - Malformed schema → `ValidationError` (file not created or modified).
+ *   - Filesystem failure during write → `Error` with file context; tmp file
+ *     cleanup is best-effort, prior schema (if any) is left byte-identical
+ *     because the rename never happened.
+ *
+ * Overwrites any existing schema at the target path; callers that need
+ * mutate-in-place semantics should use `updateSchema`.
+ */
+export declare function writeSchema(cwd: string, schemaName: string, schema: object): void;
+/**
+ * Op-correct create-or-replace of a whole schema body, layered over
+ * `writeSchema` (FGAP-077 — the Pi-tool / CLI-facing schema-write op).
+ *
+ * Where `writeSchema` is an unconditional create-or-overwrite, this surface
+ * adds an explicit operation discriminator so a caller's intent (create a NEW
+ * schema vs. replace an EXISTING one) is enforced rather than silently
+ * coerced:
+ *   - `operation: "create"` requires the schema to be ABSENT — a collision
+ *     with an existing schema throws (use `replace` to overwrite).
+ *   - `operation: "replace"` requires the schema to be PRESENT — a missing
+ *     target throws (use `create` to initialize).
+ *   - any other operation string throws before any disk read.
+ *
+ * The presence check reuses `readSchema` (returns `null` when absent) and the
+ * single private `schemaWritePath` helper so there is one path source. The
+ * actual write delegates to `writeSchema`, which meta-validates against the
+ * draft-07 meta-schema and writes atomically (tmp + rename); this surface adds
+ * no second validation or write path.
+ *
+ * Migration boundary (DECIDED, FGAP-077): this op writes the schema JSON and
+ * meta-validates the schema body. It does NOT migrate existing block items
+ * forward when a `replace` changes the schema's `version`. A breaking
+ * evolution is handled at READ time by `validateBlockWithMigration`, which
+ * throws a version mismatch until a code-level `MigrationFn` is registered via
+ * `createRegistry().register(...)` — and there is no Pi-tool surface for
+ * registering a `MigrationFn`. This surface does not (and must not) emit an
+ * "items exist at old version" warning: that would require reading block files
+ * to assess data-layer impact from inside the schema-write layer, inverting
+ * the read-time / write-time layering.
+ *
+ * `ctx` is accepted and IGNORED: schema files carry no author-attestation
+ * fields, so there is nothing to stamp. The parameter is present for call-site
+ * parity with the attestation-aware block-write / config-write surfaces
+ * (mirrors `amendConfigEntry`'s ctx-forwarding parameter, which forwards to
+ * `writeConfig`; here there is no author-bearing target to forward to).
+ *
+ * `opts.dryRun` runs the SAME meta-validator `writeSchema` uses against the
+ * supplied body and returns `{ written: false }` without touching disk —
+ * keeping ONE validation path (no re-implemented validation for the preview).
+ */
+export declare function writeSchemaChecked(cwd: string, schemaName: string, schema: object, operation: "create" | "replace", ctx?: DispatchContext, opts?: {
+    dryRun?: boolean;
+}): {
+    written: boolean;
+    operation: "create" | "replace";
+    schemaPath: string;
+};
+/**
+ * Read the current schema at `<contextDir>/schemas/<schemaName>.schema.json`,
+ * pass it to `mutator`, meta-validate the result, and atomically write it
+ * back. Throws if:
+ *   - the schema does not exist (`Error` — caller must initialize first)
+ *   - the on-disk schema parses as JSON but the mutator output fails meta
+ *     validation (`ValidationError`)
+ *   - the filesystem write fails (`Error`, prior schema unchanged)
+ *
+ * `mutator` receives a deep-readable reference to the parsed schema; it is
+ * the caller's responsibility to return a fresh object rather than mutate
+ * in place — callers that mutate in place still work because the result is
+ * what writeSchema sees, but the convention is "mutator returns the new
+ * schema" so the call site reads as a transform.
+ */
+export declare function updateSchema(cwd: string, schemaName: string, mutator: (current: object) => object): void;
+export { ValidationError };
+//# sourceMappingURL=schema-write.d.ts.map

package/dist/schema-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-write.d.ts","sourceRoot":"","sources":["../src/schema-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAA6B,MAAM,uBAAuB,CAAC;AAgBnF;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAuBjF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,QAAQ,GAAG,SAAS,EAC/B,GAAG,CAAC,EAAE,eAAe,EACrB,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACzB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,QAAQ,GAAG,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAgC3E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAoBxG;AAID,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/schema-write.js

@@ -0,0 +1,210 @@
+/**
+ * Canonical schema-write surface — read / write / mutate the JSON Schemas
+ * that live alongside project blocks under `<contextDir>/schemas/`.
+ *
+ * Closes structurally:
+ *   - FGAP-011 (canonical schema-write surface): every schema mutation that
+ *     would otherwise reach `.project/schemas/*.schema.json` via direct fs
+ *     edits now has a single typed entry point. Direct fs writes remain
+ *     possible but are now a parallel ungated path that should be retired
+ *     in any future schema mutation per the F-006-bypass-pattern discipline.
+ *
+ * Contract:
+ *   - All schemas pass through AJV draft-07 meta-schema validation before
+ *     they touch disk. Malformed schemas throw `ValidationError` with the
+ *     meta-violation details; the file is not created or modified.
+ *   - Atomic on-disk semantics — writes go to a `<file>.schema-write-<pid>.tmp`
+ *     sibling and are renamed into place. A failed write leaves the prior
+ *     schema byte-identical.
+ *   - Schema files land at `<resolveContextDir(cwd)>/schemas/<schemaName>.schema.json`,
+ *     routed through `schemaPath` (context-dir) so write resolution is identical
+ *     to read resolution — pointer-canonical, `config.root` is NOT a path input
+ *     (FGAP-079 / DEC-0045). Previously based on a config.root-honoring
+ *     path-builder, which diverged from the pointer-canonical read side.
+ *
+ * Out-of-scope for step 3:
+ *   - Schema $id + version + $ref + migration registry (FGAP-006, step 4)
+ *   - Schema diff / change-log tooling
+ *   - Cross-package opinionated mutators (e.g. add-author-fields shorthand)
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { schemaPath } from "./context-dir.js";
+import { ValidationError, validateSchemaAgainstMeta } from "./schema-validator.js";
+/**
+ * `<resolveContextDir(cwd)>/schemas/<schemaName>.schema.json` — canonical schema
+ * path, routed through `schemaPath` (context-dir) so write resolution is
+ * BYTE-IDENTICAL to read resolution (FGAP-079 / DEC-0045). Previously this was
+ * based on a config.root-honoring path-builder, which diverged from the
+ * pointer-canonical read side (`schemaPath` / `validateBlockWithMigration`) under
+ * a non-default `config.root` — schemas would be written where reads/validation
+ * could not find them. Delegating to `schemaPath` collapses the two paths to one
+ * source AND inherits its `assertSubstrateName` guard (path-traversal rejection).
+ */
+function schemaWritePath(cwd, schemaName) {
+    return schemaPath(cwd, schemaName);
+}
+/**
+ * Read a schema from `<contextDir>/schemas/<schemaName>.schema.json` and
+ * return the parsed object. Returns `null` when the file does not exist —
+ * absence is a normal pre-write state, not an error. Throws when the file
+ * exists but is unreadable or contains invalid JSON.
+ *
+ * Note: this reader does NOT meta-validate. Callers that need a guarantee
+ * the file holds a valid schema should pipe the result through
+ * `validateSchemaAgainstMeta` themselves; `updateSchema` already does.
+ */
+export function readSchema(cwd, schemaName) {
+    const p = schemaWritePath(cwd, schemaName);
+    if (!fs.existsSync(p))
+        return null;
+    let raw;
+    try {
+        raw = fs.readFileSync(p, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`readSchema: failed to read ${p}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`readSchema: invalid JSON in ${p}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Atomically write `schema` to `<contextDir>/schemas/<schemaName>.schema.json`
+ * after validating it against the JSON Schema draft-07 meta-schema.
+ *
+ * Failure modes:
+ *   - Malformed schema → `ValidationError` (file not created or modified).
+ *   - Filesystem failure during write → `Error` with file context; tmp file
+ *     cleanup is best-effort, prior schema (if any) is left byte-identical
+ *     because the rename never happened.
+ *
+ * Overwrites any existing schema at the target path; callers that need
+ * mutate-in-place semantics should use `updateSchema`.
+ */
+export function writeSchema(cwd, schemaName, schema) {
+    const p = schemaWritePath(cwd, schemaName);
+    // (1) Meta-schema validation BEFORE any disk activity.
+    validateSchemaAgainstMeta(schema, `schema '${schemaName}'`);
+    // (2) Ensure the schemas/ directory exists.
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    // (3) Atomic write: tmp + rename.
+    const tmpPath = `${p}.schema-write-${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(tmpPath, `${JSON.stringify(schema, null, 2)}\n`, "utf-8");
+        fs.renameSync(tmpPath, p);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            /* best-effort cleanup — surface the original error below */
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`writeSchema: failed to write ${p}: ${msg}`);
+    }
+}
+/**
+ * Op-correct create-or-replace of a whole schema body, layered over
+ * `writeSchema` (FGAP-077 — the Pi-tool / CLI-facing schema-write op).
+ *
+ * Where `writeSchema` is an unconditional create-or-overwrite, this surface
+ * adds an explicit operation discriminator so a caller's intent (create a NEW
+ * schema vs. replace an EXISTING one) is enforced rather than silently
+ * coerced:
+ *   - `operation: "create"` requires the schema to be ABSENT — a collision
+ *     with an existing schema throws (use `replace` to overwrite).
+ *   - `operation: "replace"` requires the schema to be PRESENT — a missing
+ *     target throws (use `create` to initialize).
+ *   - any other operation string throws before any disk read.
+ *
+ * The presence check reuses `readSchema` (returns `null` when absent) and the
+ * single private `schemaWritePath` helper so there is one path source. The
+ * actual write delegates to `writeSchema`, which meta-validates against the
+ * draft-07 meta-schema and writes atomically (tmp + rename); this surface adds
+ * no second validation or write path.
+ *
+ * Migration boundary (DECIDED, FGAP-077): this op writes the schema JSON and
+ * meta-validates the schema body. It does NOT migrate existing block items
+ * forward when a `replace` changes the schema's `version`. A breaking
+ * evolution is handled at READ time by `validateBlockWithMigration`, which
+ * throws a version mismatch until a code-level `MigrationFn` is registered via
+ * `createRegistry().register(...)` — and there is no Pi-tool surface for
+ * registering a `MigrationFn`. This surface does not (and must not) emit an
+ * "items exist at old version" warning: that would require reading block files
+ * to assess data-layer impact from inside the schema-write layer, inverting
+ * the read-time / write-time layering.
+ *
+ * `ctx` is accepted and IGNORED: schema files carry no author-attestation
+ * fields, so there is nothing to stamp. The parameter is present for call-site
+ * parity with the attestation-aware block-write / config-write surfaces
+ * (mirrors `amendConfigEntry`'s ctx-forwarding parameter, which forwards to
+ * `writeConfig`; here there is no author-bearing target to forward to).
+ *
+ * `opts.dryRun` runs the SAME meta-validator `writeSchema` uses against the
+ * supplied body and returns `{ written: false }` without touching disk —
+ * keeping ONE validation path (no re-implemented validation for the preview).
+ */
+export function writeSchemaChecked(cwd, schemaName, schema, operation, ctx, opts) {
+    void ctx; // accepted for call-site parity; schema files carry no author fields.
+    const target = schemaWritePath(cwd, schemaName);
+    // (1) Operation discriminator — reject unknown ops before any disk read.
+    if (operation !== "create" && operation !== "replace") {
+        throw new Error(`writeSchemaChecked: unknown operation '${operation}' — expected create | replace`);
+    }
+    // (2) Presence guard — readSchema returns null when the file is absent.
+    const existing = readSchema(cwd, schemaName);
+    if (operation === "create" && existing !== null) {
+        throw new Error(`writeSchemaChecked: create collision — schema '${schemaName}' already exists at ${target}; use operation 'replace' to overwrite`);
+    }
+    if (operation === "replace" && existing === null) {
+        throw new Error(`writeSchemaChecked: replace target missing — schema '${schemaName}' does not exist at ${target}; use operation 'create'`);
+    }
+    // (3) Dry-run: meta-validate via the SAME validator writeSchema uses, no write.
+    if (opts?.dryRun) {
+        validateSchemaAgainstMeta(schema, `schema '${schemaName}' (dry-run)`);
+        return { written: false, operation, schemaPath: target };
+    }
+    // (4) Commit: writeSchema re-meta-validates + writes atomically (tmp + rename).
+    writeSchema(cwd, schemaName, schema);
+    return { written: true, operation, schemaPath: target };
+}
+/**
+ * Read the current schema at `<contextDir>/schemas/<schemaName>.schema.json`,
+ * pass it to `mutator`, meta-validate the result, and atomically write it
+ * back. Throws if:
+ *   - the schema does not exist (`Error` — caller must initialize first)
+ *   - the on-disk schema parses as JSON but the mutator output fails meta
+ *     validation (`ValidationError`)
+ *   - the filesystem write fails (`Error`, prior schema unchanged)
+ *
+ * `mutator` receives a deep-readable reference to the parsed schema; it is
+ * the caller's responsibility to return a fresh object rather than mutate
+ * in place — callers that mutate in place still work because the result is
+ * what writeSchema sees, but the convention is "mutator returns the new
+ * schema" so the call site reads as a transform.
+ */
+export function updateSchema(cwd, schemaName, mutator) {
+    const current = readSchema(cwd, schemaName);
+    if (current === null) {
+        throw new Error(`updateSchema: schema '${schemaName}' does not exist at ${schemaWritePath(cwd, schemaName)}; use writeSchema to create it`);
+    }
+    const next = mutator(current);
+    // validateSchemaAgainstMeta will throw ValidationError on a malformed result;
+    // we deliberately let that propagate so the caller sees the meta details.
+    validateSchemaAgainstMeta(next, `schema '${schemaName}' (post-mutator)`);
+    // Reuse writeSchema for the atomic write — it re-validates, which is a
+    // belt-and-braces double-check rather than wasted work, since the second
+    // validation is fast on the same AJV instance and guarantees disk state
+    // matches a meta-valid schema even if a future refactor moves the
+    // pre-write check.
+    writeSchema(cwd, schemaName, next);
+}
+// Re-export ValidationError so consumers don't need a dual import to catch
+// the only error subclass thrown from the meta-validation path.
+export { ValidationError };
+//# sourceMappingURL=schema-write.js.map

package/dist/schema-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-write.js","sourceRoot":"","sources":["../src/schema-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAEnF;;;;;;;;;GASG;AACH,SAAS,eAAe,CAAC,GAAW,EAAE,UAAkB;IACvD,OAAO,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,UAAkB;IACzD,MAAM,CAAC,GAAG,eAAe,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAC3C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACJ,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACzG,CAAC;IAED,IAAI,CAAC;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAW,CAAC;IAClC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1G,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,UAAkB,EAAE,MAAc;IAC1E,MAAM,CAAC,GAAG,eAAe,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAE3C,uDAAuD;IACvD,yBAAyB,CAAC,MAAM,EAAE,WAAW,UAAU,GAAG,CAAC,CAAC;IAE5D,4CAA4C;IAC5C,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEnD,kCAAkC;IAClC,MAAM,OAAO,GAAG,GAAG,CAAC,iBAAiB,OAAO,CAAC,GAAG,MAAM,CAAC;IACvD,IAAI,CAAC;QACJ,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3E,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAI,CAAC;YACJ,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACR,4DAA4D;QAC7D,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;IAC9D,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,kBAAkB,CACjC,GAAW,EACX,UAAkB,EAClB,MAAc,EACd,SAA+B,EAC/B,GAAqB,EACrB,IAA2B;IAE3B,KAAK,GAAG,CAAC,CAAC,sEAAsE;IAEhF,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAEhD,yEAAyE;IACzE,IAAI,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,0CAA0C,SAAS,+BAA+B,CAAC,CAAC;IACrG,CAAC;IAED,wEAAwE;IACxE,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAC7C,IAAI,SAAS,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CACd,kDAAkD,UAAU,uBAAuB,MAAM,wCAAwC,CACjI,CAAC;IACH,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACd,wDAAwD,UAAU,uBAAuB,MAAM,0BAA0B,CACzH,CAAC;IACH,CAAC;IAED,gFAAgF;IAChF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QAClB,yBAAyB,CAAC,MAAM,EAAE,WAAW,UAAU,aAAa,CAAC,CAAC;QACtE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAC1D,CAAC;IAED,gFAAgF;IAChF,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IACrC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,UAAkB,EAAE,OAAoC;IACjG,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAC5C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACd,yBAAyB,UAAU,uBAAuB,eAAe,CAAC,GAAG,EAAE,UAAU,CAAC,gCAAgC,CAC1H,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9B,8EAA8E;IAC9E,0EAA0E;IAC1E,yBAAyB,CAAC,IAAI,EAAE,WAAW,UAAU,kBAAkB,CAAC,CAAC;IAEzE,uEAAuE;IACvE,yEAAyE;IACzE,wEAAwE;IACxE,kEAAkE;IAClE,mBAAmB;IACnB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,2EAA2E;AAC3E,gEAAgE;AAChE,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/status-vocab.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Status-vocabulary primitives — pure helpers mapping per-schema status enum
+ * values to a normalized StatusBucket, plus the config-override resolver.
+ *
+ * Extracted here (from roadmap-plan.ts) so both roadmap-plan AND context-sdk
+ * can consume the vocabulary without forming a module import cycle. This
+ * mirrors the topo.ts extraction precedent: context-sdk's currentState +
+ * validateContext (status-consistency invariants) and roadmap-plan's
+ * rollupPhaseStatus both bucket statuses; routing both through one
+ * substrate-light module (it imports only loadContext from
+ * context, which depends on neither roadmap-plan nor context-sdk)
+ * keeps the dependency graph acyclic.
+ *
+ * StatusBucket itself is declared in context.ts (the substrate type
+ * surface) and imported/re-exported here; it is NOT redeclared.
+ */
+import { type StatusBucket } from "./context.js";
+export type { StatusBucket } from "./context.js";
+/**
+ * Hardcoded baseline mapping from per-schema status enum values to
+ * StatusBucket. Per-project overrides land via config.status_buckets and
+ * shadow these defaults at lookup time (resolveStatusVocabulary spreads
+ * the user map over the defaults so user keys win on collision).
+ *
+ * Mappings cover the going-forward conception vocabulary — the status enums
+ * of packages/pi-context/samples/schemas/ (the DEC-0037 15-kind canon, all
+ * also live in this repo's .project/ registered block_kinds). Per DEC-0036
+ * (registry/ is retiring in favor of samples/→.context) these defaults track
+ * the conception, NOT the retired registry-only vocab (audit pass/fail/warn/
+ * skip, project inception/planning/development/maintenance, decisions
+ * revisit/tentative) — a substrate needing such vocab declares it via
+ * config.status_buckets (DEC-0025 override surface), never here.
+ *   - decisions.status:      open | enacted | superseded
+ *   - framework-gaps.status: identified | accepted | in-progress | closed | wontfix
+ *   - tasks.status:          planned | in-progress | completed | blocked | cancelled
+ *   - features.status:       proposed | approved | in-progress | in-review | complete | blocked | cancelled
+ *   - story.status:          proposed | ready | in-progress | in-review | complete | blocked
+ *   - research.status:       planned | in-progress | complete | stale | superseded | revised
+ *   - requirements.status:   proposed | accepted | deferred | implemented | verified
+ *   - verification.status:   passed | failed | partial | skipped
+ *   - spec-reviews.status:   not-started | in-progress | complete | abandoned
+ *   - layer-plans.status:    draft | proposed | decided | in-progress | complete | abandoned
+ *   - issues.status:         open | resolved | deferred
+ *   - phase.status:          planned | in-progress | completed
+ *
+ * status-vocab.test.ts guards completeness: every samples/schemas status enum
+ * value must resolve here (only the intended terminal-not-complete set may map
+ * to "unknown"). Values still bucket to "unknown" without throwing — caller
+ * decides whether unknown statuses are warning-worthy (validateRoadmaps emits
+ * roadmap_status_unknown_value when relevant).
+ */
+export declare const STATUS_VOCABULARY_DEFAULTS: Record<string, StatusBucket>;
+/**
+ * Resolve the active status-vocabulary map for `cwd` — defaults shadowed
+ * by config.status_buckets entries. Pure: builds a fresh map per call;
+ * callers caching for hot paths (rollupPhaseStatus over many phases)
+ * should pass the resolved map in directly.
+ */
+export declare function resolveStatusVocabulary(cwd: string): Record<string, StatusBucket>;
+//# sourceMappingURL=status-vocab.d.ts.map

package/dist/status-vocab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-vocab.d.ts","sourceRoot":"","sources":["../src/status-vocab.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAE9D,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CA+CnE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAGjF"}

package/dist/status-vocab.js

@@ -0,0 +1,109 @@
+/**
+ * Status-vocabulary primitives — pure helpers mapping per-schema status enum
+ * values to a normalized StatusBucket, plus the config-override resolver.
+ *
+ * Extracted here (from roadmap-plan.ts) so both roadmap-plan AND context-sdk
+ * can consume the vocabulary without forming a module import cycle. This
+ * mirrors the topo.ts extraction precedent: context-sdk's currentState +
+ * validateContext (status-consistency invariants) and roadmap-plan's
+ * rollupPhaseStatus both bucket statuses; routing both through one
+ * substrate-light module (it imports only loadContext from
+ * context, which depends on neither roadmap-plan nor context-sdk)
+ * keeps the dependency graph acyclic.
+ *
+ * StatusBucket itself is declared in context.ts (the substrate type
+ * surface) and imported/re-exported here; it is NOT redeclared.
+ */
+import { loadContext } from "./context.js";
+/**
+ * Hardcoded baseline mapping from per-schema status enum values to
+ * StatusBucket. Per-project overrides land via config.status_buckets and
+ * shadow these defaults at lookup time (resolveStatusVocabulary spreads
+ * the user map over the defaults so user keys win on collision).
+ *
+ * Mappings cover the going-forward conception vocabulary — the status enums
+ * of packages/pi-context/samples/schemas/ (the DEC-0037 15-kind canon, all
+ * also live in this repo's .project/ registered block_kinds). Per DEC-0036
+ * (registry/ is retiring in favor of samples/→.context) these defaults track
+ * the conception, NOT the retired registry-only vocab (audit pass/fail/warn/
+ * skip, project inception/planning/development/maintenance, decisions
+ * revisit/tentative) — a substrate needing such vocab declares it via
+ * config.status_buckets (DEC-0025 override surface), never here.
+ *   - decisions.status:      open | enacted | superseded
+ *   - framework-gaps.status: identified | accepted | in-progress | closed | wontfix
+ *   - tasks.status:          planned | in-progress | completed | blocked | cancelled
+ *   - features.status:       proposed | approved | in-progress | in-review | complete | blocked | cancelled
+ *   - story.status:          proposed | ready | in-progress | in-review | complete | blocked
+ *   - research.status:       planned | in-progress | complete | stale | superseded | revised
+ *   - requirements.status:   proposed | accepted | deferred | implemented | verified
+ *   - verification.status:   passed | failed | partial | skipped
+ *   - spec-reviews.status:   not-started | in-progress | complete | abandoned
+ *   - layer-plans.status:    draft | proposed | decided | in-progress | complete | abandoned
+ *   - issues.status:         open | resolved | deferred
+ *   - phase.status:          planned | in-progress | completed
+ *
+ * status-vocab.test.ts guards completeness: every samples/schemas status enum
+ * value must resolve here (only the intended terminal-not-complete set may map
+ * to "unknown"). Values still bucket to "unknown" without throwing — caller
+ * decides whether unknown statuses are warning-worthy (validateRoadmaps emits
+ * roadmap_status_unknown_value when relevant).
+ */
+export const STATUS_VOCABULARY_DEFAULTS = {
+    // → complete
+    resolved: "complete",
+    completed: "complete",
+    complete: "complete",
+    done: "complete",
+    enacted: "complete",
+    implemented: "complete",
+    passed: "complete",
+    archived: "complete",
+    closed: "complete", // framework-gaps: gap resolved/done
+    verified: "complete", // requirements: terminal-done, beyond "implemented"
+    // → in_progress
+    in_progress: "in_progress",
+    "in-progress": "in_progress",
+    active: "in_progress",
+    accepted: "in_progress",
+    "in-review": "in_progress", // features/story: under review, still active (not yet complete)
+    revised: "in_progress", // research: transient state during re-investigation
+    partial: "in_progress", // verification: incomplete — NOT a clean pass, must not assert complete
+    // → blocked
+    blocked: "blocked",
+    paused: "blocked",
+    failed: "blocked",
+    // → todo
+    open: "todo",
+    todo: "todo",
+    planned: "todo",
+    proposed: "todo",
+    draft: "todo",
+    identified: "todo",
+    "not-started": "todo",
+    pending: "todo",
+    approved: "todo", // features: approved to build, not yet started
+    ready: "todo", // story/features: refined + ready to pick up, not started
+    decided: "todo", // layer-plans: plan decided to execute, before in-progress
+    // superseded / cancelled / deferred / abandoned / wontfix / skipped / stale
+    // bucket to unknown — terminal-but-not-complete states that don't fit the
+    // linear progress narrative. Roadmap/plan rollups treat them as "doesn't
+    // count toward progress" rather than as complete or todo.
+    superseded: "unknown",
+    cancelled: "unknown",
+    deferred: "unknown",
+    abandoned: "unknown", // layer-plans/spec-reviews: work stopped, not completed
+    wontfix: "unknown", // framework-gaps: decided not to address
+    skipped: "unknown", // verification: waived/not run — must not assert complete
+    stale: "unknown", // research: grounding no longer authoritative (degraded-complete)
+};
+/**
+ * Resolve the active status-vocabulary map for `cwd` — defaults shadowed
+ * by config.status_buckets entries. Pure: builds a fresh map per call;
+ * callers caching for hot paths (rollupPhaseStatus over many phases)
+ * should pass the resolved map in directly.
+ */
+export function resolveStatusVocabulary(cwd) {
+    const ctx = loadContext(cwd);
+    return { ...STATUS_VOCABULARY_DEFAULTS, ...(ctx.config?.status_buckets ?? {}) };
+}
+//# sourceMappingURL=status-vocab.js.map

package/dist/status-vocab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-vocab.js","sourceRoot":"","sources":["../src/status-vocab.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,WAAW,EAAqB,MAAM,cAAc,CAAC;AAI9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAiC;IACvE,aAAa;IACb,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,UAAU;IACrB,QAAQ,EAAE,UAAU;IACpB,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,UAAU;IACnB,WAAW,EAAE,UAAU;IACvB,MAAM,EAAE,UAAU;IAClB,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,UAAU,EAAE,oCAAoC;IACxD,QAAQ,EAAE,UAAU,EAAE,oDAAoD;IAC1E,gBAAgB;IAChB,WAAW,EAAE,aAAa;IAC1B,aAAa,EAAE,aAAa;IAC5B,MAAM,EAAE,aAAa;IACrB,QAAQ,EAAE,aAAa;IACvB,WAAW,EAAE,aAAa,EAAE,gEAAgE;IAC5F,OAAO,EAAE,aAAa,EAAE,oDAAoD;IAC5E,OAAO,EAAE,aAAa,EAAE,wEAAwE;IAChG,YAAY;IACZ,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,SAAS;IACjB,MAAM,EAAE,SAAS;IACjB,SAAS;IACT,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,MAAM;IACf,QAAQ,EAAE,MAAM;IAChB,KAAK,EAAE,MAAM;IACb,UAAU,EAAE,MAAM;IAClB,aAAa,EAAE,MAAM;IACrB,OAAO,EAAE,MAAM;IACf,QAAQ,EAAE,MAAM,EAAE,+CAA+C;IACjE,KAAK,EAAE,MAAM,EAAE,0DAA0D;IACzE,OAAO,EAAE,MAAM,EAAE,2DAA2D;IAC5E,4EAA4E;IAC5E,0EAA0E;IAC1E,yEAAyE;IACzE,0DAA0D;IAC1D,UAAU,EAAE,SAAS;IACrB,SAAS,EAAE,SAAS;IACpB,QAAQ,EAAE,SAAS;IACnB,SAAS,EAAE,SAAS,EAAE,wDAAwD;IAC9E,OAAO,EAAE,SAAS,EAAE,yCAAyC;IAC7D,OAAO,EAAE,SAAS,EAAE,0DAA0D;IAC9E,KAAK,EAAE,SAAS,EAAE,kEAAkE;CACpF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAW;IAClD,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC7B,OAAO,EAAE,GAAG,0BAA0B,EAAE,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,IAAI,EAAE,CAAC,EAAE,CAAC;AACjF,CAAC"}

package/dist/test-helpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared test helpers for pi-project tests — mock factories for ctx and pi.
+ */
+/**
+ * Create a mock extension context for testing.
+ */
+export declare function mockCtx(cwd: string): any;
+/**
+ * Create a mock pi API for testing.
+ */
+export declare function mockPi(): any;
+//# sourceMappingURL=test-helpers.d.ts.map

package/dist/test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAS7B,GAAG,CACR;AAED;;GAEG;AACH,wBAAgB,MAAM,IAKhB,GAAG,CACR"}

package/dist/test-helpers.js

@@ -0,0 +1,28 @@
+/**
+ * Shared test helpers for pi-project tests — mock factories for ctx and pi.
+ */
+/**
+ * Create a mock extension context for testing.
+ */
+export function mockCtx(cwd) {
+    return {
+        cwd,
+        hasUI: false,
+        ui: {
+            setWidget: () => { },
+            notify: () => { },
+            setStatus: () => { },
+        },
+    };
+}
+/**
+ * Create a mock pi API for testing.
+ */
+export function mockPi() {
+    const messages = [];
+    return {
+        sendMessage: (msg, opts) => messages.push({ msg, opts }),
+        _messages: messages,
+    };
+}
+//# sourceMappingURL=test-helpers.js.map

package/dist/test-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.js","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW;IAClC,OAAO;QACN,GAAG;QACH,KAAK,EAAE,KAAK;QACZ,EAAE,EAAE;YACH,SAAS,EAAE,GAAG,EAAE,GAAE,CAAC;YACnB,MAAM,EAAE,GAAG,EAAE,GAAE,CAAC;YAChB,SAAS,EAAE,GAAG,EAAE,GAAE,CAAC;SACnB;KACM,CAAC;AACV,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,MAAM;IACrB,MAAM,QAAQ,GAAU,EAAE,CAAC;IAC3B,OAAO;QACN,WAAW,EAAE,CAAC,GAAQ,EAAE,IAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;QAClE,SAAS,EAAE,QAAQ;KACZ,CAAC;AACV,CAAC"}

package/dist/topo.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Generic topological sort + cycle detection — a pure utility with no
+ * substrate dependency. Extracted here (from roadmap-plan.ts) so both
+ * roadmap-plan and context-sdk can consume it without forming a module
+ * import cycle (context-sdk.currentState + roadmap-plan both topo-order).
+ *
+ * Returns:
+ *   order  — dependency-respecting id order (Kahn's algorithm; stable,
+ *     preserves input order within a stratum).
+ *   cycles — array of cycle paths, each a string[] starting and ending
+ *     with the same id. Empty when the graph is acyclic.
+ *
+ * Callers choose whether cycles are fatal.
+ */
+export declare function topoSort<T>(nodes: T[], idOf: (n: T) => string, deps: (n: T) => string[]): {
+    order: string[];
+    cycles: string[][];
+};
+//# sourceMappingURL=topo.d.ts.map

package/dist/topo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo.d.ts","sourceRoot":"","sources":["../src/topo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACzB,KAAK,EAAE,CAAC,EAAE,EACV,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,EACtB,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,EAAE,GACtB;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,CAkFzC"}