@sema-agent/wiki-gate 0.0.0-stage → 7.67.1

package/LICENSE

@@ -0,0 +1,107 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             clay (github.com/clayboby)
+Licensed Work:        @sema-agent/core (sema-core) and the satellite packages
+                      published from this repository (currently
+                      @sema-agent/mods-kernel, @sema-agent/primitives,
+                      @sema-agent/core-stores-sql and @sema-agent/wiki-gate)
+                      (formerly published as @sema-ai/core)
+                      The Licensed Work is (c) 2026 clay.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      personal, educational, research, or other
+                      non-commercial purposes. Commercial production use
+                      requires a commercial license from the Licensor.
+Change Date:          2030-07-13
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact the Licensor.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Third-party notices
+
+Versions of this package up to and including 1.277.1 were published under the
+MIT License; those published copies remain governed by the license they were
+distributed under. This package incorporates design and (where noted) prompt
+content adapted from MIT-licensed projects — see NOTICE.md for attributions.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# @sema-agent/wiki-gate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The sema wiki gates: one reader module with three gate entries — anchors, freshness, coverage — and the stamp tool,
+over the repository a configuration object names. A wiki page carries sentences marked with their evidence level and
+the refs they rest on; the gates answer whether every claim is marked, whether every ref still resolves to what was
+stamped, and whether every source the repository requires (for the wiki genre, also the shipped feature rows) is on
+some page.
+
+## One rule set
+
+The gate holds every page directory it is pointed at — `docs/wiki` and `docs/manual` alike — to one rule set: the
+genre, and with it the directory, is chosen by the entry's configuration object, never by a page's own header, and the
+package opens no second interface for another genre. The genre is a word of the package's frozen genre table, `GENRES`
+(`wiki` → `docs/wiki`, `manual` → `docs/manual`); a row names its directory, its readers, the evidence levels it admits
+and the coverage it requires of its own. The wiki is read by embedders, deployers and callers, admits `G`, `P`, `V` and
+`I`, and requires the shipped feature rows; the manual is read by users, scripters and admins, admits `G`, `U`, `P` and
+`I`, and requires nothing of its own. A `U` sentence cites one `crit:<repo>@<X.Y.Z>:<cell>` key, and it is evidence only
+while the acceptance index judges that cell `pass` and no later cell supersedes or retires it. A word the table does not
+hold is every entry's refusal (exit 2), by name — there is no default genre and no directory member to name instead.
+
+The rules — page shape, markers, refs, digests, severities, corrections, the stamp — are the package's and read the same
+in every repository. A repository hands in its own readers (its export surface, its closed-set and contract-sentence
+registries, its configuration catalog, its literal tables, its internal work-item name form, its test reader when its
+tests are not vitest, its acceptance index and its criteria as it publishes them) and its own generators. A ref whose
+kind needs a reader the repository does not configure is an anchors finding that says so. A source the repository names
+among its `required` or `reported` sources comes with its reader: one named without a reader is every entry's refusal
+(exit 2), and the coverage verdict line names each required source with its coverage. The page index (`page-index`),
+the genre table (`genre-table`) and the table of knob fields (`knob-fields`) are the package's own generators, held by
+every repository; a repository generator spelled like any of them is every entry's refusal.
+
+A generator whose region is a table of configuration knobs names the fields its columns render with `rowFields`, out of
+`KNOB_FIELDS`. The anchors gate then holds the region to that table: an unknown field, a field named twice, a missing
+required field (`name`, `readPoints`) and a header row of another width are findings, and so is a knob row whose
+`readPoints` cell holds no `path:line` coordinate. The gate reads the shape of a coordinate, never whether the file
+and the line exist, and it judges a generator only by what the generator declares: a table rendered without a
+`rowFields` declaration is not read as a table of knobs. The package scans no source for read points; the generator of
+the repository that owns the catalog computes them.
+
+## Install
+
+```sh
+npm install --save-dev @sema-agent/wiki-gate
+```
+
+ES modules only (`"type": "module"`), Node >= 20.18.1. One entry, `.`; there are no deep paths. Its one dependency is
+`typescript` at an exact version: the digests a stamp writes are read through that compiler's printer, so another
+version could read the same declaration to another digest.
+
+## Use
+
+```js
+import { wikiAnchors, wikiFreshness, wikiCoverage, runWikiGate } from "@sema-agent/wiki-gate";
+
+const config = {
+  root: "/path/to/repo",       // every path is relative to it
+  genre: "wiki",               // its row of GENRES names the page directory ("manual" = docs/manual, the same rules)
+  redFrom: { wiki: "7.69.0" }, // per genre: below it a finding warns, from it on a finding fails
+  readers: { /* snapshot, closedSets, contracts, catalog, tableValues, workItemName, pin, acceptanceIndex, criterionText */ },
+  generators: (read) => ({ /* name → { render: (...args) => ({ text, refs }), covers?, rowFields? } */ }),
+  required: { /* source name → its reader; one named without a reader cannot be judged */ },
+  reported: { /* source name → its reader; counted, never failed */ },
+  // optional: identity, releaseDistance, bans, preflight
+};
+
+const r = wikiAnchors(config, { strict: true });
+// r.exit: 0 = no failure (warnings counted), 1 = at least one failure, 2 = cannot judge (r.couldNotJudge says why)
+// r.line: the verdict line every run speaks — a gate that judged nothing never looks like a green one
+```
+
+`runWikiGate(config, { argv })` is the command line over the same entries and the stamp:
+`anchors|freshness [--strict] [<page.md> …]`, `coverage [--strict] [--comms <dir>] [--report]`, `stamp <page.md> …`; each
+also takes `--test <dir>` (the acceptance checkout) and `--corrections <dir>` (the correction-record checkout).
+`--report` prints the coverage report as a table (source, cited, size, cited %). An option a command does not take is
+refused by name (exit 2).
+
+`citedByPages(tree, pages)` is the one reading of "what the pages cite" (feature rows on `feats:`, and for each source the
+ids cited through a ref of its kind or covered by a generated region); the coverage gate counts from it, and a
+repository's release tooling can ask it whether a name a release moved is on a page.
+
+A finding is a warning while the repository's own `package.json` version is below its `redFrom` version for the page's
+genre and a failure from that version on; `strict` takes the version out. A severity a finding carries of its own holds
+under every reading: a `crit:` cell that is not a passing, current one, and an open correction, fail under every
+reading; an old `V` run, or an old `U` cell, is a warning.
+
+## Version
+
+`@sema-agent/wiki-gate@X.Y.Z` is cut with `@sema-agent/core@X.Y.Z`: the same version number, built from the same
+commit. A package version moves with every core release whether or not the gates changed. It does not take core.
+
+## Source and package
+
+In the sema-core repository the gates run through that repository's own binding, which loads this package's source
+(tsx's `tsImport`) with the repository's readers, so a gate run needs no build. The package published from the same
+source is its `tsc` output, and the two do not differ: the package's frozen export surface
+(`test/export-surface.snapshot.json`), and the tarball test that imports the three entries from a packed tarball and
+judges the same sample pages green and broken pages red, are the proof.

package/dist/acceptance.d.ts

@@ -0,0 +1,45 @@
+/** The verdicts an acceptance cell may carry. Only `pass` vouches for a sentence. */
+export declare const ACCEPTANCE_STATES: readonly string[];
+/** Where an acceptance-index checkout holds its index. */
+export declare const ACCEPTANCE_INDEX_FILE = "criteria-index/INDEX.json";
+/** An acceptance cell's immutable key read: the repository word, the release, and the cell id within that release. */
+export interface CritKey {
+    readonly repo: string;
+    readonly version: string;
+    readonly cell: string;
+}
+/**
+ * `<repo>@<X.Y.Z>:<cell>`: `core@7.66.0:G6`, `core@7.66.0:G6.a`, `cli@1.0.161:G-EN1`. Undefined for anything else.
+ */
+export declare function parseCritKey(key: string): CritKey | undefined;
+/** One cell as the index judges it now: its verdict, the digest of the text it judged, and the cells it supersedes or retires. */
+export interface AcceptanceCell {
+    readonly key: string;
+    readonly state: string;
+    readonly textSha: string;
+    readonly supersedes: readonly string[];
+    readonly retires: readonly string[];
+}
+/** An index read at one commit: every key's current cell, and which later cell supersedes or retires a key. */
+export interface AcceptanceIndex {
+    readonly commit: string;
+    readonly cells: ReadonlyMap<string, AcceptanceCell>;
+    readonly supersededBy: ReadonlyMap<string, string>;
+    readonly retiredBy: ReadonlyMap<string, string>;
+}
+/**
+ * The index text read: a JSON array of rows, each `{ key, state, textSha, supersedes?, retires? }` (other members are
+ * the owner's and are not read). The index only grows: a key written again is judged by its last row. A row that does
+ * not read this way makes the whole index unreadable — a gate never judges a cell from half an index.
+ */
+export declare function parseAcceptanceIndex(text: string, commit: string): AcceptanceIndex;
+/** How an index is read from a checkout named on the command line: undefined when none is named or the file is not there. */
+export type AcceptanceIndexReader = (testRoot: string | undefined) => AcceptanceIndex | undefined;
+/** The reader over `<checkout>/criteria-index/INDEX.json`, at the commit `commitOf` reads for the checkout. */
+export declare function acceptanceIndexAt({ commitOf }: {
+    readonly commitOf: (dir: string) => string;
+}): AcceptanceIndexReader;
+/** Why a cell is no evidence, or undefined when it vouches (`pass`, not superseded, not retired). */
+export declare function cellRefusal(index: AcceptanceIndex, key: string): string | undefined;
+/** Whether a key's version is one this repository's tree has reached. */
+export declare function keyReached(key: CritKey, version: string): boolean;

package/dist/acceptance.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { compareVersions, parseVersion } from "./versions.js";
+export const ACCEPTANCE_STATES = Object.freeze(["pass", "fail", "obs", "info", "not_constructed", "exempt"]);
+export const ACCEPTANCE_INDEX_FILE = "criteria-index/INDEX.json";
+const CRIT_KEY = /^([a-z][a-z0-9-]*)@(\d+\.\d+\.\d+):(G(?:\d+|-[A-Za-z0-9][A-Za-z0-9-]*)(?:\.[A-Za-z0-9]+)*)$/;
+export function parseCritKey(key) {
+    const m = CRIT_KEY.exec(key);
+    return m && parseVersion(m[2]) ? { repo: m[1], version: m[2], cell: m[3] } : undefined;
+}
+export function parseAcceptanceIndex(text, commit) {
+    let rows;
+    try {
+        rows = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`the acceptance index is not JSON: ${e.message}`);
+    }
+    if (!Array.isArray(rows))
+        throw new Error("the acceptance index is not an array of rows");
+    const keys = (v, at) => {
+        if (v === undefined)
+            return [];
+        if (!Array.isArray(v) || v.some((k) => typeof k !== "string" || parseCritKey(k) === undefined))
+            throw new Error(`${at} is not an array of acceptance keys`);
+        return v;
+    };
+    const cells = new Map();
+    const supersededBy = new Map();
+    const retiredBy = new Map();
+    rows.forEach((row, i) => {
+        const at = `acceptance index row ${i + 1}`;
+        if (row === null || typeof row !== "object" || Array.isArray(row))
+            throw new Error(`${at} is not an object`);
+        const r = row;
+        if (typeof r.key !== "string" || parseCritKey(r.key) === undefined)
+            throw new Error(`${at}: key ${JSON.stringify(r.key)} is not <repo>@<X.Y.Z>:<cell>`);
+        if (typeof r.state !== "string" || !ACCEPTANCE_STATES.includes(r.state))
+            throw new Error(`${at}: state ${JSON.stringify(r.state)} is not one of ${ACCEPTANCE_STATES.join(", ")}`);
+        if (typeof r.textSha !== "string" || r.textSha.length === 0)
+            throw new Error(`${at}: textSha is not a non-empty string`);
+        const cell = { key: r.key, state: r.state, textSha: r.textSha, supersedes: keys(r.supersedes, `${at}: supersedes`), retires: keys(r.retires, `${at}: retires`) };
+        cells.set(cell.key, cell);
+    });
+    for (const cell of cells.values()) {
+        for (const k of cell.supersedes)
+            supersededBy.set(k, cell.key);
+        for (const k of cell.retires)
+            retiredBy.set(k, cell.key);
+    }
+    return { commit, cells, supersededBy, retiredBy };
+}
+export function acceptanceIndexAt({ commitOf }) {
+    return (testRoot) => {
+        if (testRoot === undefined)
+            return undefined;
+        const file = join(testRoot, ACCEPTANCE_INDEX_FILE);
+        if (!existsSync(file))
+            return undefined;
+        return parseAcceptanceIndex(readFileSync(file, "utf8"), commitOf(testRoot));
+    };
+}
+export function cellRefusal(index, key) {
+    const cell = index.cells.get(key);
+    if (cell === undefined)
+        return `the acceptance index (at ${index.commit}) holds no cell ${key}`;
+    if (cell.state !== "pass")
+        return `the acceptance index (at ${index.commit}) judges ${key} \`${cell.state}\`; only \`pass\` vouches for a sentence`;
+    const by = index.supersededBy.get(key);
+    if (by !== undefined)
+        return `${key} is superseded by ${by}`;
+    const retired = index.retiredBy.get(key);
+    if (retired !== undefined)
+        return `${key} is retired by ${retired}`;
+    return undefined;
+}
+export function keyReached(key, version) {
+    return compareVersions(key.version, version) <= 0;
+}

package/dist/check.d.ts

@@ -0,0 +1,57 @@
+import { type Generated, type Generator, type WikiTree } from "./tree.js";
+import { type Severity } from "./versions.js";
+export declare const PAGE_KINDS: readonly string[];
+/** The repositories that own pages; a page-id is prefixed by one of them, or by a genre's own word for a page about the genre. */
+export declare const OWNER_REPOS: readonly string[];
+/** A frontmatter key and whether it may repeat. A key not in this table is a finding (a typo is not a new key). */
+export declare const FRONTMATTER_KEYS: Readonly<Record<string, "one" | "many">>;
+/** The gate a finding belongs to, the page and file line it points at, its sentence, and a severity of its own. */
+export interface Finding {
+    readonly gate: "anchors" | "freshness" | "coverage";
+    readonly page: string;
+    readonly line: number;
+    readonly message: string;
+    readonly fixed?: Severity;
+}
+/**
+ * What page text, marker text and generated text never carry: identifiers of the repositories' internal record. A test
+ * file path inside a `pin:` ref is a coordinate and is exempt (it is removed before these run). The work-item name form
+ * is the internal record's own reading of one, its flags kept (a global or sticky flag is dropped: each line is matched
+ * on its own); a repository that configures none has no such row. A repository's own forms (`extra`) follow the shared ones.
+ */
+export declare function publicnessBans(workItemName?: RegExp, extra?: ReadonlyArray<readonly [string, RegExp]>): ReadonlyArray<readonly [string, RegExp]>;
+/** A generator by name; a name the generators object only inherits (`constructor`) is no generator. */
+export declare const generatorOf: (tree: Pick<WikiTree, "generators">, name: string) => Generator | undefined;
+/** A region's generation, or why it cannot be had: a generator's answer that is not `{ text, refs }` is unreadable. */
+export declare function generate(gen: Generator, args: readonly string[]): Generated;
+/** The findings of one page, the digests the stamp writes, the coordinates of its refs, and its marker levels. */
+export interface PageCheck {
+    readonly findings: Finding[];
+    readonly digests: Record<string, string>;
+    readonly coords: Record<string, string>;
+    readonly levels: Record<string, number>;
+}
+/**
+ * Check one page. Findings carry the gate that owns them (`anchors` | `freshness`), a file line and a sentence.
+ * `stamp: true` is the stamp tool's reading: the stamped digests are not compared (they are about to be rewritten).
+ */
+export declare function checkPage(tree: WikiTree, rel: string, text: string, { stamp }?: {
+    stamp?: boolean;
+}): PageCheck;
+/**
+ * The page with every generated region rewritten from a fresh generation — the regions `claimBlocks` reads, so an
+ * example inside inline code or a code fence is never rewritten; a region whose generator fails is left as it is.
+ */
+export declare function regenerate(tree: WikiTree, text: string): string;
+/**
+ * The stamp: regenerate every region, then rewrite `verified:` and every `anchor:` line from the tree. Refuses (returns
+ * the anchors findings, no text) while the page has any — a stamp vouches for a page that resolves, never for one that does not.
+ */
+export declare function stampPage(tree: WikiTree, rel: string, text: string, { commit }: {
+    commit: string;
+}): {
+    text: string;
+    anchors: number;
+} | {
+    refused: Finding[];
+};