@polydeukes/core 0.4.0 → 0.6.0

package/dist/catalogue.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `catalogue.ts` — the eighteen judgment-mechanism names and the shape each one admits.
+ *
+ * A mechanism name is a coordinate the machine checks, not a label: {@link deriveShape}
+ * reads a declaration's shape from its syntax alone — which sources its `source` steps
+ * name, which relations its body relates, whether it carries a witness block — and
+ * {@link validateMechanism} refuses a declaration whose derived shape falls outside the
+ * spec of the name it carries. Nothing here runs an extraction or opens a world.
+ */
+import type { AlgebraDeclaration, RelationName } from './algebra.ts';
+/** The four axes a declaration can read, closed. This tuple is the single source of the list. */
+export declare const AXIS_NAMES: readonly ['change', 'actor', 'world', 'history'];
+/** One of the four axes — the closed vocabulary of the axis position. */
+export type Axis = (typeof AXIS_NAMES)[number];
+/** The judgment mechanisms, closed. A name outside this tuple is refused, never coerced. */
+export declare const MECHANISM_NAMES: readonly ['pairing', 'companion', 'monotonic-order', 'fingerprint-sync', 'producer-owned', 'self-absolution-ban', 'actor-scope', 'precedent', 'phase-order', 'turn-locality', 'stated-ground', 'controlled-vocabulary', 'naming', 'added-only', 'one-way-marker', 'delegated-scope', 'scoped-valve', 'forbidden-command'];
+/** One of the eighteen mechanism names. */
+export type MechanismName = (typeof MECHANISM_NAMES)[number];
+/**
+ * What one mechanism name admits: the axes it may read, the relations it may relate, and
+ * the structural markers it requires.
+ *
+ * `requiresWitness` asks for the valve block; `scopeSource` pins what the declaration may
+ * scope on; `reserved` names what will define the name, and stands in place of a
+ * shape — a reserved name admits no declaration at all.
+ */
+export type MechanismShape = {
+    axes: ReadonlySet<Axis>;
+    relations: ReadonlySet<RelationName>;
+    requiresWitness?: true;
+    scopeSource?: 'target.path' | 'command';
+    reserved?: string;
+};
+/**
+ * The blocks {@link deriveShape} reads. A declaration names itself with its `discipline`,
+ * and an entry under `declare` names itself with the entry id instead — the shape is the
+ * same either way, so the derivation takes the blocks rather than the whole document.
+ */
+export type DerivableDeclaration = Pick<AlgebraDeclaration, 'extract' | 'relate' | 'sources' | 'witness'>;
+/** The derived shape of one declaration: what its syntax says it reads and relates. */
+export type DerivedShape = {
+    axes: ReadonlySet<Axis>;
+    relations: ReadonlySet<RelationName>;
+    witness: boolean;
+};
+/** Every name's spec. The `Record` type pins the keys to {@link MECHANISM_NAMES}. */
+export declare const MECHANISM_SHAPES: Record<MechanismName, MechanismShape>;
+/**
+ * Read one declaration's shape from its syntax (pure).
+ *
+ * The axis of a source name is where the name comes from: the fixed name `actor` is the
+ * actor axis and the other six fixed names the change axis, a name the declaration's own
+ * `sources` block binds is the world axis unless the binding is of the transcript kind,
+ * which is the history axis. A name that is neither is refused by
+ * {@link validateMechanism} — skipping it would derive the empty set, which is a subset of
+ * every spec, and an axis-restricted name would load on a typo. The witness block's
+ * `extract` reads a world too, so its source steps count; its `relate` does not, because the
+ * valve's relation is not the judgment's.
+ */
+export declare function deriveShape(declaration: DerivableDeclaration): DerivedShape;
+/**
+ * Check the declaration's `mechanism` against the catalogue (throws on a mismatch).
+ *
+ * The order is the author's repair order: an unknown name first (nothing else is
+ * meaningful without a spec), then the reserved name, then the structural markers, then
+ * the axes and relations the derived shape must stay inside. Membership is subset, not
+ * equality — a name admitting two relations accepts a declaration using one of them.
+ */
+export declare function validateMechanism(declaration: AlgebraDeclaration, location: string): void;

package/dist/catalogue.js

@@ -0,0 +1,191 @@
+/**
+ * `catalogue.ts` — the eighteen judgment-mechanism names and the shape each one admits.
+ *
+ * A mechanism name is a coordinate the machine checks, not a label: {@link deriveShape}
+ * reads a declaration's shape from its syntax alone — which sources its `source` steps
+ * name, which relations its body relates, whether it carries a witness block — and
+ * {@link validateMechanism} refuses a declaration whose derived shape falls outside the
+ * spec of the name it carries. Nothing here runs an extraction or opens a world.
+ */
+import { isPlainObject } from './is-plain-object.js';
+import { FIXED_SOURCE_NAMES } from './source-names.js';
+import { ConfigValidationError } from './validation.js';
+/** The four axes a declaration can read, closed. This tuple is the single source of the list. */
+export const AXIS_NAMES = ['change', 'actor', 'world', 'history'];
+/** The judgment mechanisms, closed. A name outside this tuple is refused, never coerced. */
+export const MECHANISM_NAMES = [
+    'pairing',
+    'companion',
+    'monotonic-order',
+    'fingerprint-sync',
+    'producer-owned',
+    'self-absolution-ban',
+    'actor-scope',
+    'precedent',
+    'phase-order',
+    'turn-locality',
+    'stated-ground',
+    'controlled-vocabulary',
+    'naming',
+    'added-only',
+    'one-way-marker',
+    'delegated-scope',
+    'scoped-valve',
+    'forbidden-command',
+];
+const CHANGE = new Set(['change']);
+const WORLD = new Set(['world']);
+const ACTOR = new Set(['actor']);
+const HISTORY = new Set(['history']);
+const HISTORY_WORLD = new Set(['history', 'world']);
+const CHANGE_WORLD = new Set(['change', 'world']);
+/** The one fixed source name whose value is the actor rather than the change. */
+const ACTOR_SOURCE = 'actor';
+/** Every name's spec. The `Record` type pins the keys to {@link MECHANISM_NAMES}. */
+export const MECHANISM_SHAPES = {
+    pairing: { axes: WORLD, relations: new Set(['equal']) },
+    companion: { axes: CHANGE_WORLD, relations: new Set(['implies']) },
+    'monotonic-order': { axes: CHANGE_WORLD, relations: new Set(['ordered']) },
+    'fingerprint-sync': { axes: WORLD, relations: new Set(['equal']) },
+    'producer-owned': { axes: ACTOR, relations: new Set(['empty', 'nonEmpty']) },
+    'self-absolution-ban': {
+        axes: CHANGE,
+        relations: new Set(['unchanged', 'empty']),
+    },
+    'actor-scope': { axes: ACTOR, relations: new Set(['empty', 'nonEmpty']) },
+    // The spawn sidecar is a world-axis channel carrying session history, so a precedent
+    // read off it is still a precedent; the transcript source carries the history axis.
+    precedent: { axes: HISTORY_WORLD, relations: new Set(['nonEmpty']) },
+    'phase-order': { axes: HISTORY, relations: new Set(['ordered']) },
+    'turn-locality': { axes: HISTORY, relations: new Set(['nonEmpty']) },
+    'stated-ground': { axes: HISTORY, relations: new Set(['nonEmpty']) },
+    'controlled-vocabulary': { axes: CHANGE_WORLD, relations: new Set(['subset']) },
+    naming: {
+        axes: CHANGE,
+        relations: new Set(['empty', 'nonEmpty']),
+        scopeSource: 'target.path',
+    },
+    'added-only': { axes: CHANGE, relations: new Set(['empty']) },
+    'one-way-marker': { axes: CHANGE, relations: new Set(['subset']) },
+    'delegated-scope': {
+        axes: new Set(),
+        relations: new Set(),
+        reserved: 'the definition-time evaluator',
+    },
+    'scoped-valve': {
+        axes: new Set(AXIS_NAMES),
+        relations: new Set([
+            'empty',
+            'nonEmpty',
+            'equal',
+            'subset',
+            'implies',
+            'ordered',
+            'unchanged',
+        ]),
+        requiresWitness: true,
+    },
+    // A command-line ban scopes on the command it reads: a world with no shell call carries
+    // no `command`, and a scope-less reader would refuse every file-changing call as unjudgeable.
+    'forbidden-command': {
+        axes: CHANGE,
+        relations: new Set(['empty']),
+        scopeSource: 'command',
+    },
+};
+/** The names a rejection message lists so the author sees what is admitted. */
+function quotedList(names) {
+    return names.map((name) => `'${name}'`).join(', ');
+}
+/** Whether one `sources` binding names the session history rather than a world value. */
+function isTranscriptSource(binding) {
+    return isPlainObject(binding) && binding.transcript === true;
+}
+/** The source names one extract block's `source` steps name, in declaration order. */
+function sourceNamesOf(extract) {
+    if (extract === undefined)
+        return [];
+    const names = [];
+    for (const steps of Object.values(extract)) {
+        for (const step of steps) {
+            if (isPlainObject(step) && step.op === 'source' && typeof step.of === 'string') {
+                names.push(step.of);
+            }
+        }
+    }
+    return names;
+}
+/** Every source name the body and the valve read, in declaration order. */
+function sourceNames(declaration) {
+    return [...sourceNamesOf(declaration.extract), ...sourceNamesOf(declaration.witness?.extract)];
+}
+/**
+ * Read one declaration's shape from its syntax (pure).
+ *
+ * The axis of a source name is where the name comes from: the fixed name `actor` is the
+ * actor axis and the other six fixed names the change axis, a name the declaration's own
+ * `sources` block binds is the world axis unless the binding is of the transcript kind,
+ * which is the history axis. A name that is neither is refused by
+ * {@link validateMechanism} — skipping it would derive the empty set, which is a subset of
+ * every spec, and an axis-restricted name would load on a typo. The witness block's
+ * `extract` reads a world too, so its source steps count; its `relate` does not, because the
+ * valve's relation is not the judgment's.
+ */
+export function deriveShape(declaration) {
+    const bindings = declaration.sources ?? {};
+    const axes = new Set();
+    for (const name of sourceNames(declaration)) {
+        if (FIXED_SOURCE_NAMES.includes(name)) {
+            axes.add(name === ACTOR_SOURCE ? 'actor' : 'change');
+        }
+        else if (name in bindings) {
+            axes.add(isTranscriptSource(bindings[name]) ? 'history' : 'world');
+        }
+    }
+    const relations = new Set(declaration.relate.map((entry) => entry.relation.op));
+    return { axes, relations, witness: declaration.witness !== undefined };
+}
+/** Refuse a `source` step naming neither a fixed source nor a binding of this declaration. */
+function checkSourceNames(declaration, location) {
+    const declared = new Set(Object.keys(declaration.sources ?? {}));
+    for (const name of sourceNames(declaration)) {
+        if (FIXED_SOURCE_NAMES.includes(name) || declared.has(name))
+            continue;
+        const bindings = declared.size === 0 ? 'and this declaration binds none' : `or ${quotedList([...declared])}`;
+        throw new ConfigValidationError(`${location} reads the source '${name}', which is neither one of ${quotedList(FIXED_SOURCE_NAMES)} ${bindings}`);
+    }
+}
+/**
+ * Check the declaration's `mechanism` against the catalogue (throws on a mismatch).
+ *
+ * The order is the author's repair order: an unknown name first (nothing else is
+ * meaningful without a spec), then the reserved name, then the structural markers, then
+ * the axes and relations the derived shape must stay inside. Membership is subset, not
+ * equality — a name admitting two relations accepts a declaration using one of them.
+ */
+export function validateMechanism(declaration, location) {
+    const mechanism = declaration.mechanism;
+    if (!MECHANISM_NAMES.includes(mechanism)) {
+        throw new ConfigValidationError(`${location} mechanism is '${mechanism}' — must be one of ${quotedList(MECHANISM_NAMES)}`);
+    }
+    const spec = MECHANISM_SHAPES[mechanism];
+    if (spec.reserved !== undefined) {
+        throw new ConfigValidationError(`${location} mechanism '${mechanism}' is reserved for ${spec.reserved}, which does not exist yet`);
+    }
+    checkSourceNames(declaration, location);
+    const shape = deriveShape(declaration);
+    if (spec.requiresWitness === true && !shape.witness) {
+        throw new ConfigValidationError(`${location} mechanism '${mechanism}' needs a witness block — the valve is its whole shape`);
+    }
+    if (spec.scopeSource !== undefined && declaration.scope?.source !== spec.scopeSource) {
+        const actual = declaration.scope === undefined
+            ? 'this declaration has no scope block'
+            : `this declaration scopes on '${declaration.scope.source}'`;
+        throw new ConfigValidationError(`${location} mechanism '${mechanism}' scopes on '${spec.scopeSource}' — ${actual}`);
+    }
+    const outsideAxes = [...shape.axes].filter((axis) => !spec.axes.has(axis));
+    const outsideRelations = [...shape.relations].filter((relation) => !spec.relations.has(relation));
+    if (outsideAxes.length > 0 || outsideRelations.length > 0) {
+        throw new ConfigValidationError(`${location} mechanism '${mechanism}' expects relations ${quotedList([...spec.relations])} on axes ${quotedList([...spec.axes])}; this declaration relates ${quotedList([...shape.relations])} on ${quotedList([...shape.axes])}`);
+    }
+}

package/dist/config.d.ts

@@ -1,18 +1,17 @@
 /**
- * Config schema v2 + `defineConfig()` validator — config as data (CONFIG-04).
+ * Config schema and the `defineConfig()` validator — config as data.
  *
- * This is the single settings surface the three areas share (covenant's `protectedPaths`,
- * ledger's `testCmd`, memory's ticket pattern all reference this shape). Since schema v2 the
- * input is pure JSON-representable data: `testCmd` is a `{scope}` template string, and
- * `defineConfig` is the runtime validator for parsed unknown data (the CONFIG-03 loader feeds
- * it values the compiler never saw). It stays a pure function — zero file I/O, zero runtime
- * dependencies (hand-rolled validation; the published JSON Schema is a sibling artifact the
- * source never reads).
+ * The single settings surface the areas share. The input is pure JSON-representable data,
+ * and `defineConfig` is the runtime validator for parsed unknown values the compiler never
+ * saw. It stays a pure function — no file I/O and no runtime dependencies: validation is
+ * hand-rolled, and the published JSON Schema is a sibling artifact this source never reads.
  */
-/** Conventional default telemetry log path (PRD §4.3) — local-only observation data. */
+import { type AlgebraDeclaration } from './algebra.ts';
+export { ConfigValidationError } from './validation.ts';
+/** Conventional default telemetry log path — local-only observation data. */
 export declare const DEFAULT_TELEMETRY_LOG_PATH = ".polydeukes/roi.log";
 /**
- * `LanguageProfile` — the unit of the language axis (PRD §4.1).
+ * `LanguageProfile` — the unit of the language axis.
  *
  * `testCmd` is a shell command template: every literal `{scope}` token is substituted at
  * resolve time, and the core only carries the resulting string — it never interprets it.
@@ -27,80 +26,86 @@ export type LanguageProfile = {
     testCmd: string;
 };
 /**
- * `DisciplineForbid` — the delta-family predicate value (COVENANT-10 §4.1).
+ * `AlgebraDeclarationBody` — an algebra declaration minus its name.
  *
- * The string shorthand is equivalent to `{ added }`; `removed`/`present` directions are
- * deferred (COVENANT-12) and rejected by validation.
+ * An entry names its declaration with the entry's `id`, so the block under `declare`
+ * carries every other key and never `discipline`.
  */
-export type DisciplineForbid = string | {
-    added: string;
-};
+export type AlgebraDeclarationBody = Omit<AlgebraDeclaration, 'discipline'>;
+/**
+ * `EnforceLevel` — an entry's own rung on the promotion ladder. `advise` records a break
+ * without stopping it; `block` pins the entry at block whatever default the ladder later
+ * adopts. Absence means advise; `block` is the promotion rung.
+ */
+export type EnforceLevel = 'block' | 'advise';
 /**
- * `DisciplineEntry` — one user-declared discipline (COVENANT-10 §4.1). Pure JSON data.
+ * `DisciplineEntry` — one user-declared discipline. Pure JSON data.
  *
- * Exactly one predicate key (`forbid` | `immutable` | `forbidCommand` |
- * `requirePrecedent`) per entry; `in`/`except` scope the delta and context families.
- * Compilation is the covenant package's job — the core validates compilability of regex
- * strings but never executes them.
+ * The judgment is the `declare` block and nothing else; the other three keys name the
+ * entry, explain it, and set its level. Compilation is the covenant package's job — the
+ * core validates the block's grammar but never runs an extraction.
  */
 export type DisciplineEntry = {
     /** unique handle — telemetry label and verdict reason prefix */
     id: string;
-    /** prose rationale, documentation only — never judged */
+    /** prose rationale — never judged, and carried into the break message */
     why?: string;
-    /** delta/context-family scope: glob(s) the file path must match (absent = every file change) */
-    in?: string | string[];
-    /** delta/context-family scope: glob(s) excluded after `in` */
-    except?: string | string[];
-    /** delta family — string shorthand = { added } */
-    forbid?: DisciplineForbid;
-    /** path family — its own glob is the scope */
-    immutable?: string | string[];
-    /** command family — regex over shell command strings */
-    forbidCommand?: string;
-    /** context-family trigger: added-direction delta regex (absent = every in-scope change) */
-    when?: string;
-    /**
-     * context family — the session evidence one edit requires beforehand. Exactly one
-     * evidence key. The core owns and fully validates `command`; every other key is
-     * adapter vocabulary whose value passes through verbatim (CONFIG-07 layering).
-     */
-    requirePrecedent?: Record<string, unknown>;
+    /** the author's level; composes with the observer's surface level, lenient side winning */
+    enforce?: EnforceLevel;
+    /** one judgment written as data — the entry's `id` is the declaration's name */
+    declare: AlgebraDeclarationBody;
+};
+/**
+ * `DisciplineDraft` — an unpromoted discipline: the promotion ladder's first rung,
+ * registered as prose ahead of any declaration.
+ *
+ * A draft is declared, never inferred — only the literal `draft: true` makes one, and an
+ * entry with neither a `declare` block nor the marker stays a validation error. It carries
+ * no declaration, produces no registration, no judgment, and no telemetry row;
+ * `pdks explain` renders it as unpromoted.
+ */
+export type DisciplineDraft = {
+    /** unique handle in the same label space as judged entries and meta-covenant labels */
+    id: string;
+    /** the draft's whole body — required prose, unlike the judged families' optional why */
+    why: string;
+    /** the explicit marker; only the literal true exists (false is rejected as dead data) */
+    draft: true;
 };
 /**
- * `PolydeukesConfig` — the input shape a user writes (PRD §4.1). JSON-serializable data.
+ * `PolydeukesConfig` — the input shape a user writes. JSON-serializable data.
  *
  * Language keys (`typescript`, `python`, …) are user *values*, not the core's vocabulary —
  * no language or tool literal appears in the core source.
  */
 export type PolydeukesConfig = {
-    /** IDE schema reference (CONFIG-03) — accepted and ignored, never part of the resolution */
+    /** IDE schema reference — accepted and ignored, never part of the resolution */
     $schema?: string;
     /** language axis, first-class. keys are user values ('typescript', 'python', …) */
     languages: Record<string, LanguageProfile>;
-    /** raw protected path patterns — normalization is CONFIG-02's job */
+    /** raw protected path patterns — normalized downstream, never here */
     protectedPaths?: string[];
     /**
-     * adapter namespaces (CONFIG-07) — keys are ecosystem values (never validated), each
-     * value is that adapter's own settings object, passed through verbatim (the vocabulary
-     * belongs to the adapter, whose own validator judges the contents)
+     * adapter namespaces — keys are ecosystem values (never validated), each value is that
+     * adapter's own settings object, passed through verbatim (the vocabulary belongs to the
+     * adapter, whose own validator judges the contents)
      */
     adapters?: Record<string, Record<string, unknown>>;
     telemetry?: {
-        /** conventional default applies when omitted (§4.3) */
+        /** conventional default applies when omitted */
         logPath?: string;
     };
     /** user-declared disciplines — validated here, compiled by the covenant package */
-    disciplines?: DisciplineEntry[];
+    disciplines?: (DisciplineEntry | DisciplineDraft)[];
     /**
-     * TTL witness values for the covenant valve seam (CONFIG-05) — consumed at
-     * assembly time, validated here
+     * TTL witness values for the covenant valve seam — consumed at assembly time,
+     * validated here
      */
     witness?: {
         /**
          * the agreed phrase a human types alone on a message's first line — quoting it
-         * mid-sentence is a mention, not an invocation (COVENANT-15). Non-empty after
-         * trimming; the value itself is free (provenance, not secrecy, is the defence)
+         * mid-sentence is a mention, not an invocation. Non-empty after trimming; the value
+         * itself is free, since provenance rather than secrecy is the defence
          */
         token: string;
         /** validity window in minutes from the user message's timestamp — finite and > 0 */
@@ -110,11 +115,11 @@ export type PolydeukesConfig = {
 /**
  * `ResolvedLanguageProfile` — a {@link LanguageProfile} with its template compiled.
  *
- * Consumers keep the callable shape (`testCmd(scope)`), identical to schema v1 (LEDGER-05).
+ * Consumers keep the callable shape (`testCmd(scope)`).
  */
 export type ResolvedLanguageProfile = {
     productionGlob: string | string[];
-    /** compiled from the template — consumers keep the callable shape (LEDGER-05) */
+    /** compiled from the template — consumers keep the callable shape */
     testCmd: (scope: string) => string;
 };
 /**
@@ -130,28 +135,23 @@ export type ResolvedConfig = {
     telemetry: {
         logPath: string;
     };
-    /** validated discipline data, passed through verbatim (absent stays absent) */
+    /**
+     * validated judged entries only — drafts are split out at resolution time so the
+     * covenant compiler has no path that receives one. Present whenever the input
+     * declared a `disciplines` array, holding exactly its judged entries in order.
+     */
     disciplines?: DisciplineEntry[];
+    /** validated drafts in declaration order (absent when the input carries none) */
+    drafts?: DisciplineDraft[];
     /** validated witness data, passed through verbatim (absent stays absent) */
     witness?: {
         token: string;
         ttlMinutes: number;
     };
 };
-/**
- * `ConfigValidationError` — raised when a config fails structural validation (PRD §4.3).
- *
- * The message names the offending field path so the developer sees exactly what is wrong.
- * This throw is a developer-time error (config authoring), a different axis from the
- * covenant runtime's fail-closed exit code — a bad config should fail loud and early.
- */
-export declare class ConfigValidationError extends Error {
-    constructor(message: string);
-}
 /**
  * Validate parsed unknown data as a {@link PolydeukesConfig} and return a
- * {@link ResolvedConfig} with defaults filled and templates compiled (PRD §4.3).
- * Pure — no file I/O.
+ * {@link ResolvedConfig} with defaults filled and templates compiled. Pure — no file I/O.
  *
  * Throws {@link ConfigValidationError} (naming the offending field path) when the top level
  * is not a plain object, any object level carries an unknown key, `languages` is