@panaversity/ksor 0.0.39 → 0.0.41

package/templates/scaffold/system/site/record/load.ts

@@ -0,0 +1,129 @@
+/**
+ * The one place the record module touches the filesystem: find the instance
+ * and read the tree into `RecordFiles`. `resolveInstanceDir` is the shared
+ * `--instance` resolution build spec §1 names for `build`, `migrate`,
+ * `takedown` and `ingest` — the nearest ancestor `instance.md`, or null.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+import type { RecordFiles } from "./check";
+import type { ScaffoldStructure } from "./hygiene";
+
+const CONTROL_FILES = ["instance.md", ".ksor/governance.yaml", ".ksor/takedowns.yaml"] as const;
+/** Files the operating system writes behind the author's back: ignored, never reported. */
+const OS_JUNK = new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
+
+/** The directory holding the nearest `instance.md` at or above `start`, or null when none. */
+export function resolveInstanceDir(start: string): string | null {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (existsSync(path.join(dir, "instance.md"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Everything the checker reads, under the record at `root`. Symlinks are not
+ * followed — they are reported, and the checker refuses them (a dangling one
+ * crashed the old checker with a raw ENOENT before any other problem was
+ * reported, review 2026-08-18).
+ */
+/**
+ * What the LOADER always produces, as against the in-memory `RecordFiles` a
+ * test may hand-build: `assets` and `symlinks` are optional on that type
+ * because a fixture map omits them, and every caller that reads a real tree
+ * then had to re-prove they exist. The site's build was the one that noticed
+ * (`'record.assets' is possibly 'undefined'`) — its `tsc` runs over the
+ * template, which this repo's own typecheck does not.
+ */
+export interface LoadedRecord extends RecordFiles {
+  readonly assets: ReadonlyMap<string, Uint8Array>;
+  readonly symlinks: readonly string[];
+}
+
+export function loadRecord(root: string): LoadedRecord {
+  const files = new Map<string, string>();
+  const assets = new Map<string, Uint8Array>();
+  const dirs: string[] = [];
+  const symlinks: string[] = [];
+  for (const rel of CONTROL_FILES) {
+    const abs = path.join(root, rel);
+    if (existsSync(abs) && statSync(abs).isFile()) files.set(rel, readFileSync(abs, "utf8"));
+  }
+  const knowledge = path.join(root, "knowledge");
+  if (existsSync(knowledge)) walk(knowledge, "knowledge", { files, assets, dirs, symlinks });
+  return { files, dirs, assets, symlinks };
+}
+
+interface Walked {
+  readonly files: Map<string, string>;
+  readonly assets: Map<string, Uint8Array>;
+  readonly dirs: string[];
+  readonly symlinks: string[];
+}
+
+function walk(abs: string, rel: string, out: Walked): void {
+  for (const entry of readdirSync(abs, { withFileTypes: true }).sort((a, b) =>
+    a.name < b.name ? -1 : 1,
+  )) {
+    if (OS_JUNK.has(entry.name)) continue;
+    const childAbs = path.join(abs, entry.name);
+    const childRel = `${rel}/${entry.name}`;
+    if (entry.isSymbolicLink()) {
+      out.symlinks.push(childRel);
+    } else if (entry.isDirectory()) {
+      out.dirs.push(childRel);
+      walk(childAbs, childRel, out);
+    } else if (entry.isFile() && /\.(md|yaml)$/.test(entry.name)) {
+      out.files.set(childRel, readFileSync(childAbs, "utf8"));
+    } else if (entry.isFile()) {
+      out.assets.set(childRel, new Uint8Array(readFileSync(childAbs)));
+    }
+  }
+}
+
+const SITE_BUILD_DIRS = new Set(["node_modules", ".next", ".source", ".staged-knowledge", "out"]);
+
+/** The project around the record, for `checkScaffoldStructure` (the emitted checker's structure rules). */
+export function loadScaffoldStructure(root: string): ScaffoldStructure {
+  const claudeMd = path.join(root, "CLAUDE.md");
+  const digests = (dir: string): Map<string, string> => {
+    const out = new Map<string, string>();
+    if (!existsSync(dir)) return out;
+    for (const file of filesUnder(dir, new Set())) {
+      out.set(
+        path.relative(dir, file).split(path.sep).join("/"),
+        createHash("sha256").update(readFileSync(file)).digest("hex"),
+      );
+    }
+    return out;
+  };
+  const site = path.join(root, "system", "site");
+  const siteContentFiles = existsSync(site)
+    ? filesUnder(site, SITE_BUILD_DIRS)
+        .filter((p) => /\.mdx?$/i.test(p))
+        .map((p) => path.relative(root, p).split(path.sep).join("/"))
+        .sort()
+    : [];
+  return {
+    claudeMd: existsSync(claudeMd) ? readFileSync(claudeMd, "utf8") : null,
+    agentsSkills: digests(path.join(root, ".agents", "skills")),
+    claudeSkills: digests(path.join(root, ".claude", "skills")),
+    siteContentFiles,
+  };
+}
+
+function filesUnder(dir: string, skip: ReadonlySet<string>): string[] {
+  return readdirSync(dir, { withFileTypes: true })
+    .sort((a, b) => (a.name < b.name ? -1 : 1))
+    .flatMap((entry) => {
+      const p = path.join(dir, entry.name);
+      if (entry.isDirectory()) return skip.has(entry.name) ? [] : filesUnder(p, skip);
+      // lstat, not the dirent: a dangling symlink is neither a file nor a directory to readdir.
+      return lstatSync(p).isFile() ? [p] : [];
+    });
+}

package/templates/scaffold/system/site/record/lock.ts

@@ -0,0 +1,306 @@
+/**
+ * `build.lock.json` (build spec §2): the committed record of one build —
+ * what was published, from which commit, with which toolchain — and the
+ * `build_id` every projection stamps. Pure: the CLI gathers texts and git
+ * facts, this module decides what the lock says. `build_id` covers everything
+ * a projection reads and NOTHING that merely describes the run (`as_of`,
+ * `source_commit`, `dirty`), so the same tree with the same toolchain yields
+ * the same id unless `as_of` crosses a lifecycle boundary — in which case a
+ * different admitted set honestly gets a different id (R21).
+ */
+import { createHash } from "node:crypto";
+
+import { z } from "zod";
+
+import { overlaps } from "../lib/audience-rule";
+import { admitsLifecycle, type LifecycleStatus } from "../lib/lifecycle-rule";
+import { denies, type Denial } from "./ledger";
+
+/** OKF at the commit the record spec pins (record spec §1). */
+export const OKF_PIN: {
+  readonly version: "0.2";
+  readonly commit: string;
+  readonly spec_sha256: string;
+} = {
+  version: "0.2",
+  commit: "ad30107c31c06aec8a7d5636e0d1058118604e6f",
+  spec_sha256: "26aa5da029278939f914e578107242d9607d4f2dc5fe153272b82f9ed1030101",
+};
+
+export const LOCK_FORMAT = 1;
+
+export type Drafts = "hidden" | "shown";
+
+const hex64 = z.string().regex(/^[0-9a-f]{64}$/, "a sha256 hex digest");
+const viewerList = z.array(z.string().min(1));
+
+const lockSchema = z
+  .object({
+    format: z.literal(LOCK_FORMAT),
+    build_id: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+    ksor_version: z.string().min(1),
+    okf: z.object({ version: z.string(), commit: z.string(), spec_sha256: z.string() }).strict(),
+    source_commit: z.string().nullable(),
+    dirty: z.boolean(),
+    as_of: z.string().min(1),
+    drafts: z.enum(["hidden", "shown"]),
+    instance_sha256: hex64,
+    policy_sha256: hex64,
+    ledger_sha256: hex64,
+    ledger_entries: z.array(z.object({ id: z.string().min(1), digest: hex64 }).strict()),
+    audiences: z
+      .object({ registry: z.array(z.string()), viewers: z.record(z.string(), viewerList) })
+      .strict(),
+    documents: z.array(
+      z
+        .object({
+          path: z.string().min(1),
+          sha256: hex64,
+          status: z.enum(["draft", "stable", "deprecated"]),
+          audience: z.array(z.string()),
+          admitted: z.array(z.string()),
+        })
+        .strict(),
+    ),
+    companions: z.array(z.object({ path: z.string().min(1), sha256: hex64 }).strict()),
+    assets: z.array(z.object({ path: z.string().min(1), sha256: hex64 }).strict()),
+    indexes: z.array(z.object({ path: z.string().min(1), sha256: hex64 }).strict()),
+  })
+  .strict();
+
+export interface LockDocument {
+  /** Bundle-relative, with `.md`. */
+  readonly path: string;
+  readonly sha256: string;
+  readonly status: LifecycleStatus;
+  readonly audience: readonly string[];
+  /** Canonical viewer names whose machine artefacts contain it at `as_of`, sorted. */
+  readonly admitted: readonly string[];
+}
+
+export interface Lock {
+  readonly format: typeof LOCK_FORMAT;
+  readonly build_id: string;
+  readonly ksor_version: string;
+  readonly okf: typeof OKF_PIN;
+  readonly source_commit: string | null;
+  readonly dirty: boolean;
+  readonly as_of: string;
+  readonly drafts: Drafts;
+  readonly instance_sha256: string;
+  readonly policy_sha256: string;
+  readonly ledger_sha256: string;
+  /** `(id, digest)` per ledger entry, sorted by id — the baseline the next build compares TEXT against. */
+  readonly ledger_entries: readonly { readonly id: string; readonly digest: string }[];
+  readonly audiences: {
+    readonly registry: readonly string[];
+    readonly viewers: Readonly<Record<string, readonly string[]>>;
+  };
+  readonly documents: readonly LockDocument[];
+  readonly companions: readonly { readonly path: string; readonly sha256: string }[];
+  /**
+   * Every non-markdown file of the bundle, by bytes. The site publishes these,
+   * so a lock that stopped at the markdown left the images and PDFs — often
+   * where a record's substance actually is — outside "what was checked".
+   */
+  readonly assets: readonly { readonly path: string; readonly sha256: string }[];
+  /**
+   * The §8 indexes this build GENERATED, by bytes — the only files in
+   * `knowledge/` the build writes rather than reads, and the surface an
+   * external reader parses to find anything at all. They belonged to no other
+   * section (the checker skips `index.md`, `companions` is the attachment
+   * kinds, `assets` is the non-markdown), so the record of what was published
+   * stopped short of the file that lists what was published.
+   */
+  readonly indexes: readonly { readonly path: string; readonly sha256: string }[];
+}
+
+export type LockResult =
+  | { readonly ok: true; readonly lock: Lock }
+  | { readonly ok: false; readonly why: string };
+
+export function parseLock(text: string): LockResult {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    return { ok: false, why: `not JSON: ${String(error).split("\n")[0] ?? ""}` };
+  }
+  const parsed = lockSchema.safeParse(value);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    return {
+      ok: false,
+      why: `\`${issue?.path.map(String).join(".") || "(root)"}\`: ${issue?.message ?? "invalid"}`,
+    };
+  }
+  return { ok: true, lock: parsed.data as Lock };
+}
+
+export function sha256Hex(data: string | Uint8Array): string {
+  return createHash("sha256")
+    .update(typeof data === "string" ? Buffer.from(data, "utf8") : data)
+    .digest("hex");
+}
+
+export interface BuildIdInputs {
+  readonly documents: readonly {
+    readonly path: string;
+    readonly sha256: string;
+    readonly admitted: readonly string[];
+  }[];
+  readonly companions: readonly { readonly path: string; readonly sha256: string }[];
+  readonly assets: readonly { readonly path: string; readonly sha256: string }[];
+  readonly indexes: readonly { readonly path: string; readonly sha256: string }[];
+  readonly instance_sha256: string;
+  readonly policy_sha256: string;
+  readonly ledger_sha256: string;
+  readonly ksor_version: string;
+  readonly drafts: Drafts;
+}
+
+/** `sha256:<hex>` over a canonical serialisation of everything a projection reads (build spec §2). */
+export function buildIdOf(inputs: BuildIdInputs): string {
+  const canonical = {
+    documents: [...inputs.documents]
+      .map((d) => [d.path, d.sha256, [...d.admitted].sort()])
+      .sort((a, b) => compare(String(a[0]), String(b[0]))),
+    companions: [...inputs.companions]
+      .map((c) => [c.path, c.sha256])
+      .sort((a, b) => compare(a[0] ?? "", b[0] ?? "")),
+    assets: [...inputs.assets]
+      .map((a) => [a.path, a.sha256])
+      .sort((a, b) => compare(a[0] ?? "", b[0] ?? "")),
+    // The index bytes are a pure function of inputs already hashed here, so
+    // including them cannot change an id twice — it states directly what the
+    // rest of this object only implies, and a generator whose output moved
+    // without its inputs moving goes red rather than publishing quietly under
+    // an id that says nothing changed.
+    indexes: [...inputs.indexes]
+      .map((i) => [i.path, i.sha256])
+      .sort((a, b) => compare(a[0] ?? "", b[0] ?? "")),
+    instance_sha256: inputs.instance_sha256,
+    policy_sha256: inputs.policy_sha256,
+    ledger_sha256: inputs.ledger_sha256,
+    ksor_version: inputs.ksor_version,
+    drafts: inputs.drafts,
+  };
+  return `sha256:${sha256Hex(JSON.stringify(canonical))}`;
+}
+
+/** The canonical viewer lists: `public` alone, and `[public, X]` for each registered audience. */
+export function canonicalViewers(audiences: readonly string[]): Record<string, string[]> {
+  const viewers: Record<string, string[]> = { public: ["public"] };
+  for (const a of audiences) viewers[a] = ["public", a];
+  return viewers;
+}
+
+export interface AdmissionConcept {
+  /** Bundle-relative id (path without `.md`). */
+  readonly id: string;
+  readonly status: LifecycleStatus;
+  readonly effectiveFrom: number | null;
+  readonly staleAfter: number | null;
+  readonly audience: readonly string[];
+}
+
+/**
+ * The viewer names whose MACHINE artefacts contain the concept at `asOf`:
+ * stable, effective, unexpired, not denied by an in-force ledger entry, and
+ * audience-overlapping. Drafts are never on a machine surface, so the drafts
+ * switch does not enter here. Sorted, so the lock is stable.
+ */
+export function admittedViewersOf(
+  concept: AdmissionConcept,
+  viewers: Readonly<Record<string, readonly string[]>>,
+  asOf: number,
+  inForceDenials: readonly Denial[],
+): string[] {
+  if (!admitsLifecycle(concept, "machine", asOf, "hidden")) return [];
+  if (denies(inForceDenials, concept.id)) return [];
+  return Object.entries(viewers)
+    .filter(([, list]) => overlaps(list, concept.audience))
+    .map(([name]) => name)
+    .sort();
+}
+
+export interface LockInput {
+  readonly ksorVersion: string;
+  readonly sourceCommit: string | null;
+  readonly dirty: boolean;
+  /** Epoch ms. */
+  readonly asOf: number;
+  readonly drafts: Drafts;
+  readonly instanceText: string;
+  readonly policyText: string;
+  /** Null when the ledger file does not exist. */
+  readonly ledgerText: string | null;
+  readonly ledgerEntries: readonly { readonly id: string; readonly digest: string }[];
+  /** Registered audiences, from the policy. */
+  readonly audiences: readonly string[];
+  readonly concepts: readonly (AdmissionConcept & { readonly text: string })[];
+  readonly companions: readonly { readonly path: string; readonly text: string }[];
+  /** Bundle-relative path → raw bytes, for every non-markdown file of the record. */
+  readonly assets: readonly { readonly path: string; readonly bytes: Uint8Array }[];
+  /** Bundle-relative path → the §8 index text this build generated (`index.md`, `policies/index.md`). */
+  readonly indexes: readonly { readonly path: string; readonly text: string }[];
+  readonly denials: readonly Denial[];
+}
+
+export function composeLock(input: LockInput): Lock {
+  const viewers = canonicalViewers(input.audiences);
+  const documents = [...input.concepts]
+    .sort((a, b) => compare(a.id, b.id))
+    .map((c) => ({
+      path: `${c.id}.md`,
+      sha256: sha256Hex(c.text),
+      status: c.status,
+      audience: [...c.audience],
+      admitted: admittedViewersOf(c, viewers, input.asOf, input.denials),
+    }));
+  const companions = [...input.companions]
+    .sort((a, b) => compare(a.path, b.path))
+    .map((c) => ({ path: c.path, sha256: sha256Hex(c.text) }));
+  const assets = [...input.assets]
+    .sort((a, b) => compare(a.path, b.path))
+    .map((a) => ({ path: a.path, sha256: sha256Hex(a.bytes) }));
+  const indexes = [...input.indexes]
+    .sort((a, b) => compare(a.path, b.path))
+    .map((i) => ({ path: i.path, sha256: sha256Hex(i.text) }));
+  const instance_sha256 = sha256Hex(input.instanceText);
+  const policy_sha256 = sha256Hex(input.policyText);
+  const ledger_sha256 = sha256Hex(input.ledgerText ?? "");
+  return {
+    format: LOCK_FORMAT,
+    build_id: buildIdOf({
+      documents,
+      companions,
+      assets,
+      indexes,
+      instance_sha256,
+      policy_sha256,
+      ledger_sha256,
+      ksor_version: input.ksorVersion,
+      drafts: input.drafts,
+    }),
+    ksor_version: input.ksorVersion,
+    okf: OKF_PIN,
+    source_commit: input.sourceCommit,
+    dirty: input.dirty,
+    as_of: new Date(input.asOf).toISOString(),
+    drafts: input.drafts,
+    instance_sha256,
+    policy_sha256,
+    ledger_sha256,
+    ledger_entries: [...input.ledgerEntries].sort((a, b) => compare(a.id, b.id)),
+    audiences: { registry: [...input.audiences].sort(), viewers },
+    documents,
+    companions,
+    assets,
+    indexes,
+  };
+}
+
+function compare(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/templates/scaffold/system/site/record/near-miss.ts

@@ -0,0 +1,37 @@
+/**
+ * "Did you mean" for a closed key set — ONE implementation.
+ *
+ * Two closed key sets refuse an unknown key and offer the nearest allowed one:
+ * the concept's profile keys and the Governance Policy's. Each carried its own
+ * byte-identical Levenshtein loop, in sibling modules of one directory, so
+ * tuning one (a different cap, transpositions) would have moved one refusal
+ * family and not the other with nothing red.
+ */
+
+/** Edit distance. Only a NEAR miss earns a refusal, so a genuine extension key is kept. */
+export function distance(a: string, b: string): number {
+  let previous = [...Array(b.length + 1).keys()];
+  for (let i = 1; i <= a.length; i += 1) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j += 1) {
+      row[j] = Math.min(
+        (previous[j] ?? 0) + 1,
+        (row[j - 1] ?? 0) + 1,
+        (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    previous = row;
+  }
+  return previous[b.length] ?? 0;
+}
+
+/** The allowed key nearest to `key`, within `max` edits; null when none is close. */
+export function nearest(key: string, allowed: readonly string[], max: number): string | null {
+  let best: readonly [string, number] | null = null;
+  for (const candidate of allowed) {
+    if (candidate === key) return null;
+    const d = distance(candidate, key);
+    if (d <= max && (best === null || d < best[1])) best = [candidate, d];
+  }
+  return best === null ? null : best[0];
+}