polydeukes 0.6.1 → 0.7.1

package/dist/covenant/ttl-witness.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `ttlWitness` — a time-boxed witness predicate.
+ *
+ * The predicate on the witness seam. Expiry is built in rather than left to the human
+ * to disarm: a human types the agreed token into the conversation, the witness holds
+ * for `ttlMs` from that user message's timestamp, then blocking resumes automatically
+ * — no stored state, every dispatch re-judges against the injected clock.
+ *
+ * Invoking the witness is distinct from talking about it: the token must stand alone on
+ * the utterance's first line, so quoting or asking about it never opens the valve. Only
+ * the token's *placement* is constrained — its value is free, and this module never
+ * inspects its shape.
+ */
+import type { WitnessPredicate } from './dispatch.ts';
+/** Configuration for {@link ttlWitness}. */
+export type TtlWitnessSpec = {
+    /**
+     * The agreed phrase a human types on the first line of a message, alone. Any value
+     * works — the defence is provenance, not secrecy, so the phrase is never checked for
+     * a prefix, a command shape, or any other form. Surrounding whitespace is trimmed at
+     * assembly (both sides of the comparison normalise the same way); trimmed-empty
+     * throws, as does a value containing a line break (it could never match a first line).
+     */
+    token: string;
+    /** Validity window in milliseconds from the user message's timestamp. Must be finite and > 0. */
+    ttlMs: number;
+    /** Injectable clock (defaults to Date.now). For test determinism. */
+    now?: () => number;
+};
+/**
+ * Build a predicate that returns `true` iff some user message carries the token
+ * within the TTL window.
+ *
+ * A message witnesses only when all hold: it comes from `transcript.findUserMessages()`
+ * (no other text surface is consulted — an AI-synthesised token never counts), the
+ * first line of its `text` equals the token once trimmed, its `timestampMs` is
+ * present, and `0 <= now() - timestampMs <= ttlMs` (closed interval; a future
+ * timestamp is rejected). A missing `timestampMs` means freshness is unprovable and
+ * defers to `resolveFailMode('evidence-absence')`, so the disposition's single source of
+ * truth stays in the core policy table.
+ *
+ * Validation is a factory-time concern: a trimmed-empty token or a non-finite /
+ * non-positive `ttlMs` throws here; the returned predicate itself never throws.
+ * The input is unused: the valve keys on session evidence, not on the payload being
+ * judged. Pure: no I/O, no state, no mutation.
+ */
+export declare function ttlWitness(spec: TtlWitnessSpec): WitnessPredicate;

package/dist/covenant/ttl-witness.js

@@ -0,0 +1,80 @@
+/**
+ * `ttlWitness` — a time-boxed witness predicate.
+ *
+ * The predicate on the witness seam. Expiry is built in rather than left to the human
+ * to disarm: a human types the agreed token into the conversation, the witness holds
+ * for `ttlMs` from that user message's timestamp, then blocking resumes automatically
+ * — no stored state, every dispatch re-judges against the injected clock.
+ *
+ * Invoking the witness is distinct from talking about it: the token must stand alone on
+ * the utterance's first line, so quoting or asking about it never opens the valve. Only
+ * the token's *placement* is constrained — its value is free, and this module never
+ * inspects its shape.
+ */
+import { resolveFailMode } from '@polydeukes/core';
+/**
+ * Build a predicate that returns `true` iff some user message carries the token
+ * within the TTL window.
+ *
+ * A message witnesses only when all hold: it comes from `transcript.findUserMessages()`
+ * (no other text surface is consulted — an AI-synthesised token never counts), the
+ * first line of its `text` equals the token once trimmed, its `timestampMs` is
+ * present, and `0 <= now() - timestampMs <= ttlMs` (closed interval; a future
+ * timestamp is rejected). A missing `timestampMs` means freshness is unprovable and
+ * defers to `resolveFailMode('evidence-absence')`, so the disposition's single source of
+ * truth stays in the core policy table.
+ *
+ * Validation is a factory-time concern: a trimmed-empty token or a non-finite /
+ * non-positive `ttlMs` throws here; the returned predicate itself never throws.
+ * The input is unused: the valve keys on session evidence, not on the payload being
+ * judged. Pure: no I/O, no state, no mutation.
+ */
+export function ttlWitness(spec) {
+    const { token: rawToken, ttlMs, now = Date.now } = spec;
+    // Normalise once, at assembly: the first line is compared trimmed, so a token
+    // carrying stray surrounding whitespace could never equal it — the valve would
+    // pass validation and then silently never open.
+    const token = rawToken.trim();
+    if (token.length === 0) {
+        throw new TypeError('ttlWitness: token must be non-empty after trimming');
+    }
+    // A token containing a line break is structurally inert: the judgment compares the
+    // FIRST LINE of an utterance, which by construction never contains one, so such a
+    // token could never match anything — the valve would pass validation and then
+    // silently refuse every utterance. Rejecting it here is validation of viability,
+    // not interpretation of the phrase (the value stays free otherwise).
+    if (/[\r\n]/.test(token)) {
+        throw new TypeError('ttlWitness: token must not contain line breaks');
+    }
+    if (!(Number.isFinite(ttlMs) && ttlMs > 0)) {
+        throw new TypeError('ttlWitness: ttlMs must be a finite positive number');
+    }
+    return (_input, transcript) => {
+        // One clock read per judgment: every message in this dispatch is measured
+        // against the same "now", so the closed-interval boundary cannot flip with
+        // a message's position in the transcript.
+        const judgedAt = now();
+        return transcript.findUserMessages().some((message) => {
+            // The first line only, compared whole: an utterance invokes the witness, it does
+            // not merely mention it. `split` keeps a leading blank line as an empty first
+            // element, so a token below it never matches, and `trim` absorbs both surrounding
+            // spaces and the trailing `\r` of a CRLF transport — CRLF only: a lone `\r` with no
+            // `\n` is not treated as a line break, so such a message fails closed (refused),
+            // never open.
+            //
+            // `trim` covers the whole Unicode space class, so a token padded with NBSP, an
+            // ideographic space, or a BOM opens the valve exactly as an ASCII-padded one does.
+            // That latitude is intentional: this seam defends provenance, not secrecy — the
+            // token is read only from `findUserMessages()`, so no AI-synthesised padding
+            // reaches it, while a human's IME or clipboard routinely supplies these.
+            const [firstLine = ''] = message.text.split('\n');
+            if (firstLine.trim() !== token)
+                return false;
+            if (message.timestampMs === undefined) {
+                return resolveFailMode('evidence-absence') === 'open';
+            }
+            const elapsed = judgedAt - message.timestampMs;
+            return elapsed >= 0 && elapsed <= ttlMs;
+        });
+    };
+}

package/dist/covenant-check.d.ts

@@ -1,72 +1,105 @@
 /**
- * `pdks covenant check` — the commit surface's composition root.
+ * `pdks covenant check` — the composition root both surfaces' callers reach through the bin.
  *
- * Assembly mirrors the session hook — loadConfig → normalizeProtectedPaths → collect →
- * dispatchCovenants — and spawns the same covenant dist bodies, so a change receives the
- * verdict a session tool call would. Each change is dispatched as its own input so
- * telemetry stays one row per file. The witness valve is a `/dev/tty` prompt that only
- * the staged domain assembles; the other domains open no commit.
+ * The judged unit is the input IR the caller hands in; this root opens no repository. Assembly
+ * mirrors the session hook — loadConfig → normalizeProtectedPaths → dispatchCovenants — and
+ * runs the same judge bodies, so a change receives the verdict a session tool call would.
+ * Each toolCall is dispatched as its own input so telemetry stays one row per file.
  *
- * fail-closed: a missing config, an unbuilt body, or a collector failure exits 2 with one
- * blocked record. An empty domain is an explicit pass with no records.
+ * fail-closed: a missing config, an input that could not be produced, or an input carrying its
+ * own `world` exits 2 with one blocked record. An input with no toolCalls is an explicit pass
+ * with no records.
  */
-import { type Observation } from '@polydeukes/adapter-git';
-import type { CovenantRegistration } from '@polydeukes/covenant';
-import { type CovenantModule } from './covenant-module.ts';
+import { type CanonicalTranscript, type CovenantInput } from '@polydeukes/core';
+import type { CovenantRegistration } from './covenant/dispatch.ts';
+import { type CovenantModule } from './covenant/module.ts';
 import { loadConfig } from './load-config.ts';
-/**
- * Which observation of the commit surface a run judges. Only the collector differs between
- * them; the IR, the assembly, and the dispatcher are one path.
- *
- * The adapter that owns the git grammar owns the type: its supply body reads a path the way
- * each observation sees the tree, and this root names the same fact for its callers.
- */
-export type CheckDomain = Observation;
 /** {@link runCovenantCheck} result — the exit code the check process leaves with. */
 export type CovenantCheckOutcome = {
     exitCode: 0 | 2;
 };
+/**
+ * `CovenantSurface` — which observation unit the input is, and so which discipline list
+ * stands beside the shared one.
+ *
+ * `session` is one call the host observed before it ran; `changeSet` is a finished change
+ * set. The caller's input mode is the whole answer — the IR's own keys never choose.
+ */
+export type CovenantSurface = 'session' | 'changeSet';
 /** `runCovenantCheck` input. */
 export type CovenantCheckSpec = {
-    /** Repository root — config discovery and staged collection both anchor here. */
+    /** Repository root — config discovery and the world axis's disk reads both anchor here. */
     repoRoot: string;
+    /**
+     * The observation to judge, or a thunk that produces it. A thunk that throws fails the
+     * run closed after the config settles, so a caller translating an input of its own leaves
+     * the same one blocked row a missing config would.
+     */
+    input: CovenantInput | (() => CovenantInput);
+    /** Which surface this input is an observation of — the caller's input mode says so. */
+    surface: CovenantSurface;
     /**
      * Overrides where telemetry is written (tests and assembly injection) — the first term
      * of the precedence, ahead of the config's `telemetry.logPath` and of the default this
      * runner settles before the config loads. Absent, both of those apply in that order.
      */
     telemetryPath?: string;
-    /** Overrides the resolved covenant dist directory (tests and assembly injection). */
-    covenantDist?: string;
+    /** Overrides the judge module the run assembles against (tests and assembly injection). */
+    covenant?: CovenantModule;
     /**
-     * TTY valve seam: writes the given prompt and returns the line a human typed, or null
-     * for no input. ABSENT means a non-TTY environment — the valve never opens, which is
-     * what keeps it human-only.
+     * The observer's posture for the whole run. ABSENT means `advise`: every break, a
+     * protected path included, lands as a row and exit 0 — the change-set surface's default, since
+     * a staged gate-file change has already passed the session surface or was made by a human,
+     * and this surface has no valve a human could answer. `block` is the caller's opt-in
+     * (`--enforce block` on the bin); an entry's own level composes lenient-wins as always.
      */
-    ttyPrompt?: (prompt: string) => string | null;
-    /** Which observation to judge. ABSENT means `staged`. */
-    domain?: CheckDomain;
+    enforce?: 'advise' | 'block';
 };
-/** {@link assembleCommitRegistrations} input — what the commit surface's assembly needs. */
-export type CommitAssemblySpec = {
+/** {@link assembleCheckRegistrations} input — what this runner's assembly needs. */
+export type CheckAssemblySpec = {
     config: ReturnType<typeof loadConfig>['config'];
     rootDir: string;
     /**
-     * The covenant surface the registrations are built from — the module the caller loaded
-     * from the resolved dist, so what judges a change is what that dist carries, and what
-     * `explain` renders is what would judge it.
+     * The judge module the registrations are built from, so what judges a change and what
+     * `explain` renders come from one surface.
      */
     covenant: CovenantModule;
+    /**
+     * Which surface these registrations judge for: `disciplines` plus `sessionDisciplines`
+     * on `session`, `disciplines` plus `changeSetDisciplines` on `changeSet`.
+     */
+    surface: CovenantSurface;
+    /** The host's tool roster. ABSENT leaves the staged names as the mutating roster. */
+    tools?: CovenantInput['tools'];
+    /** The host's session evidence. ABSENT is the absence of a session. */
+    session?: CovenantInput['session'];
+    /** The session flattened for a `transcript` binding — the runner derives it once from `session`. */
+    transcript?: CanonicalTranscript;
     witness?: CovenantRegistration['witness'];
 };
 /**
- * The commit surface's registration set — one assembly that the runner dispatches and
- * `explain` renders.
+ * This runner's registration set — one assembly that the runner dispatches and `explain`
+ * renders.
+ *
+ * The surface picks the discipline lists; the two IR keys shape the meta-covenants and
+ * nothing else — the roster says which names route to which meta-covenant, and the session
+ * says whether there is history to protect, to bind, and to read pre-state from disk for.
  */
-export declare function assembleCommitRegistrations(spec: CommitAssemblySpec): CovenantRegistration[];
+export declare function assembleCheckRegistrations(spec: CheckAssemblySpec): CovenantRegistration[];
 /**
- * Judge one observation of `repoRoot` exactly as the session surface would — the staged
- * diff by default, the working tree or a ref range on request. Async because the dispatcher
- * spawns covenant bodies. An empty domain is an explicit pass: nothing to judge, no records.
+ * The name `explain` renders the change-set surface from — the same assembly, called with
+ * `surface: 'changeSet'` and neither IR key.
+ */
+export declare const assembleChangeSetRegistrations: typeof assembleCheckRegistrations;
+/**
+ * Judge one observation of `repoRoot` exactly as the session surface would, from the IR the
+ * caller hands in. Async because the dispatcher spawns covenant bodies. An input with no
+ * toolCalls is an explicit pass: nothing to judge, no records.
+ *
+ * An input carrying a session is one call of a live agent session, so the post-hoc state
+ * comparison wraps the judgment: it runs first, reading the window the previous call left,
+ * and the re-establishment runs last, folding this call's own judged writes in. Both sides
+ * sit OUTSIDE the judgment with their own catch — a mechanism whose purpose is to record
+ * rather than stop may never reach an exit code.
  */
 export declare function runCovenantCheck(spec: CovenantCheckSpec): Promise<CovenantCheckOutcome>;