create-agent-rig 0.8.0 → 0.9.0

package/packages/cli/dist/policy/core/coverage.js

@@ -0,0 +1,253 @@
+/**
+ * The capability & degradation contract (RP-36): what each declared policy is
+ * worth on one harness surface, how that answer is established, and how it is
+ * maintained afterwards.
+ *
+ * ⚠ A LIBRARY, not a running contract. Nothing in this rig calls any of it
+ * yet: `doctor` rendering the coverage report is its own task, and so is the
+ * caller that would report observed traffic. The present tense below describes
+ * what the functions do when called, not something happening today. The
+ * rationale and the full list of what this deliberately does not do are in
+ * `docs/decisions/capability-coverage.md`.
+ *
+ * A status is established by `./probe.ts` on an occasion named from
+ * `./vocabulary.ts` (`PROBE_TRIGGERS`), and maintained from what real traffic
+ * was expected to show and did not. Three rules follow, and they are the whole
+ * design.
+ *
+ * 🔴 **A timer alone never degrades anything.** `observeExpectedSignal` takes
+ * an OBSERVATION, never an elapsed time, and this module exports no function
+ * that ages, expires or sweeps an entry — pinned by
+ * `packages/cli/test/policy-coverage.test.ts` › "exports nothing that ages,
+ * expires or sweeps an entry, so only an observation can move it", and
+ * measured end-to-end by › "reports no downgrade when a year passes and the
+ * same wiring is probed again, because elapsed time is not evidence" against
+ * its positive control. No traffic is not a failure: it is no evidence.
+ *
+ * 🔴 **Traffic lowers a status; it never raises one.** A missing signal is
+ * evidence the mechanism did not act. A present signal is evidence it acted
+ * once — not that a wiring defect the probe found has been repaired. So the
+ * only route back up is another probe: › "never raises a status on traffic: a
+ * degraded surface stays degraded until a probe says otherwise".
+ *
+ * 🔴 **Traffic that CONTRADICTS the record is its own answer.** A signal
+ * observed on a surface the map records as `UNSUPPORTED` is not a promotion
+ * and not a miss — the wiring and the traffic disagree, which is what
+ * `INTEGRATION-FAILED` names: › "a signal observed where the map says nothing
+ * is wired is a contradiction, not a pass". It is still not a pass;
+ * `qualifierFor` maps it to `UNVERIFIABLE`.
+ *
+ * **Why this module throws where its neighbours return a `Validation`.** The
+ * line is what the value IS, not how bad it is: outside data read off a disk
+ * becomes a RESULT — `snapshot: unknown` is never trusted and never throws, it
+ * becomes `INTEGRATION-FAILED` — while a value the CALLER chose (a word from a
+ * closed vocabulary, its own clock, its own claim about which build it saw) is
+ * a programming error and throws. `./evidence-matrix.ts` sits on the first
+ * side, this module's two entry points on the second.
+ *
+ * Two limits worth stating rather than leaving to be discovered. `DEGRADED`
+ * carries no verdict qualifier, so an operation on precisely the tool a
+ * degraded matcher lost does not require a qualifier from this library — the
+ * item scopes the `UNVERIFIABLE` requirement to the unenforceable states; the
+ * caller owns the operation verdict. And a `reason`
+ * supplied with a miss that does not cross the threshold is not retained;
+ * only the miss that degrades records one — › "discards the reason given with
+ * a miss that does not degrade, and records the one given with the miss that
+ * does".
+ */
+import { probePolicy } from './probe.js';
+import { EXACT_VERSION_EXPECTED, isExactVersion, ISO_8601 } from './validation.js';
+import { PROBE_TRIGGERS, UNENFORCEABLE_STATES } from './vocabulary.js';
+/**
+ * How many consecutive expected-but-absent signals degrade a supported policy.
+ *
+ * Three, not one: a single miss is as easily an operation that never reached
+ * the mechanism as a mechanism that failed to act, and a contract that
+ * degrades on it reports noise. It is a DEFAULT and not a constant — every
+ * caller may set its own, because what counts as enough evidence depends on
+ * how much traffic the surface sees.
+ */
+export const DEFAULT_DEGRADATION_THRESHOLD = 3;
+/**
+ * How much a state can enforce, as an order, for deciding what counts as a
+ * fall. `UNSUPPORTED` and `INTEGRATION-FAILED` rank together on purpose: both
+ * mean the policy cannot be relied on here, they differ in whether anything is
+ * wired at all, and calling a move between them a downgrade would report a
+ * change of diagnosis as a loss of capability.
+ *
+ * This is a DISPLAY ordering and nothing else reads it. What qualifies a
+ * verdict is `UNENFORCEABLE_STATES` in `./vocabulary.ts`, which
+ * `./decision-record.ts` reads too — keying qualification off a rank would
+ * mean a future re-rank silently changed which verdicts are UNVERIFIABLE.
+ */
+const ENFORCEMENT_RANK = {
+    SUPPORTED: 0,
+    DEGRADED: 1,
+    UNSUPPORTED: 2,
+    'INTEGRATION-FAILED': 2,
+};
+const requireTimestamp = (field, value) => {
+    if (!ISO_8601.test(value)) {
+        throw new Error(`${field} must be an ISO-8601 date-time with an explicit zone; got ${JSON.stringify(value)}`);
+    }
+};
+/**
+ * The probe's answer for every policy, as one map.
+ *
+ * `trigger` is required, and that is the point: `PROBE_TRIGGERS` names only
+ * changes to the surface, so a caller must say which change occasioned this
+ * read and cannot name an interval. `at` is the caller's clock — nothing here
+ * reads one — and it is validated, because a status whose time cannot be
+ * ordered against a change is not auditable. The surface harness and path must
+ * also name the adapter doing the read; otherwise valid wiring from one
+ * harness could be labeled as support on another.
+ */
+export function coverageFromProbe(args) {
+    const { surface, policies, adapter, snapshot, at, trigger, evidencePointer } = args;
+    if (!PROBE_TRIGGERS.includes(trigger)) {
+        throw new Error(`a probe is occasioned by one of ${PROBE_TRIGGERS.join(', ')}; got ${JSON.stringify(trigger)}`);
+    }
+    requireTimestamp('at', at);
+    if (surface.harness !== adapter.harness || surface.surface !== adapter.surfaceFile) {
+        throw new Error(`surface identity must match the adapter being probed; expected ${JSON.stringify(adapter.harness)} at ${JSON.stringify(adapter.surfaceFile)}, got ${JSON.stringify(surface.harness)} at ${JSON.stringify(surface.surface)}`);
+    }
+    // The identity is the caller's claim about WHICH build was observed, and
+    // three documents called it exact while nothing read it. A map is the shape
+    // that carries it, so this is where it is refused.
+    if (!isExactVersion(surface.harnessVersion)) {
+        throw new Error(`surface.harnessVersion ${EXACT_VERSION_EXPECTED}; got ${JSON.stringify(surface.harnessVersion)}`);
+    }
+    const entries = policies.map((policy) => {
+        const result = probePolicy(policy, adapter, snapshot);
+        const entry = {
+            policyId: policy.policyId,
+            policyVersion: policy.policyVersion,
+            mechanism: policy.mechanism,
+            status: result.state,
+            verifiedAt: at,
+            verifiedBy: 'probe',
+            triggeredBy: trigger,
+            consecutiveMisses: 0,
+        };
+        if (result.reason !== undefined)
+            entry.degradationReason = result.reason;
+        if (evidencePointer !== undefined)
+            entry.evidencePointer = evidencePointer;
+        return entry;
+    });
+    return { surface, entries };
+}
+/**
+ * Fold one observation of real traffic into an entry.
+ *
+ * `seen` is the whole input: the operation the policy judges happened, and the
+ * observable signal the mechanism should have produced either appeared or did
+ * not. There is no parameter for "and this much time has passed", because time
+ * is not evidence about a mechanism.
+ */
+export function observeExpectedSignal(entry, observation) {
+    const { seen, at, threshold = DEFAULT_DEGRADATION_THRESHOLD, reason } = observation;
+    if (!Number.isInteger(threshold) || threshold < 1) {
+        throw new Error(`the degradation threshold must be a whole number of observations, at least 1; got ${String(threshold)}`);
+    }
+    requireTimestamp('at', at);
+    if (seen) {
+        const next = {
+            ...entry,
+            consecutiveMisses: 0,
+            verifiedAt: at,
+            verifiedBy: 'traffic',
+        };
+        // A signal seen where the record says nothing is wired is not a promotion
+        // and not a miss: the wiring and the traffic disagree, and that is the
+        // state the item reserves for it. The status is not raised — see the
+        // second rule in this file's header — so the only status this branch
+        // produces is the one naming the contradiction.
+        if (entry.status === 'UNSUPPORTED') {
+            next.status = 'INTEGRATION-FAILED';
+            next.degradationReason = `the expected signal was observed although the recorded status was UNSUPPORTED, so the wiring and the traffic disagree`;
+        }
+        return next;
+    }
+    const consecutiveMisses = entry.consecutiveMisses + 1;
+    const degrades = entry.status === 'SUPPORTED' && consecutiveMisses >= threshold;
+    const next = {
+        ...entry,
+        consecutiveMisses,
+        verifiedAt: at,
+        verifiedBy: 'traffic',
+    };
+    if (!degrades)
+        return next;
+    next.status = 'DEGRADED';
+    next.degradationReason =
+        reason ??
+            `the expected observable signal was absent on ${String(consecutiveMisses)} consecutive operations`;
+    return next;
+}
+/** The entry for one policy, or `null` — never an invented status. */
+export function statusOf(map, policyId) {
+    return map.entries.find((entry) => entry.policyId === policyId) ?? null;
+}
+/**
+ * The qualifier a verdict must carry when it was produced under this state.
+ *
+ * The unenforceable states mean the question could not be put to a working
+ * mechanism, so an `allow` under either is UNVERIFIABLE rather than a pass —
+ * `./decision-record.ts` refuses the unqualified record, and
+ * `packages/cli/test/policy-coverage.test.ts` › "refuses the silent pass an
+ * unwired surface would otherwise produce, and accepts it once qualifierFor
+ * speaks" holds the two modules to it together. How far that refusal reaches is
+ * stated once, at `UNENFORCEABLE_STATES` in `./vocabulary.ts` — read it there.
+ * This sentence used to paraphrase it as well, and the paraphrase is what went
+ * stale: it still said the refusal was "a property of records built the
+ * ordinary way" after RP-153 had made it hold against a hand-built prototype
+ * too. A second copy of a fact the same sentence claims is spelled once
+ * (`rules/invariants.md`, "One mechanism, one implementation").
+ */
+export function qualifierFor(state) {
+    return UNENFORCEABLE_STATES.includes(state)
+        ? 'UNVERIFIABLE'
+        : undefined;
+}
+/**
+ * Every policy whose status fell between two maps of the same surface.
+ *
+ * Only the same policy id and declaration version present in both are compared:
+ * an entry that appeared, vanished or changed semantics is a change of what is
+ * being measured, not a capability that fell.
+ * Two maps of DIFFERENT surfaces are refused rather than diffed — the result
+ * is attributed to one surface identity, and attributing one surface's fall to
+ * another is a report an operator would act on in the wrong place.
+ */
+export function downgradesBetween(before, after) {
+    // Deliberately NOT harnessVersion. A probe before and after an upgrade
+    // carries two versions of one surface, and that pair is exactly what the
+    // `upgrade` trigger exists to compare — refusing it disabled the comparison
+    // for the case it was added for. Harness, surface and OS are what make it
+    // the same place.
+    const sameSurface = before.surface.harness === after.surface.harness &&
+        before.surface.surface === after.surface.surface &&
+        before.surface.os === after.surface.os;
+    if (!sameSurface) {
+        throw new Error('two coverage maps of different surfaces cannot be compared: a downgrade is attributed to one surface, and these name two');
+    }
+    const downgrades = [];
+    for (const next of after.entries) {
+        const previous = before.entries.find((entry) => entry.policyId === next.policyId && entry.policyVersion === next.policyVersion) ?? null;
+        if (previous === null)
+            continue;
+        if (ENFORCEMENT_RANK[next.status] <= ENFORCEMENT_RANK[previous.status])
+            continue;
+        downgrades.push({
+            surface: after.surface,
+            policyId: next.policyId,
+            from: previous.status,
+            to: next.status,
+            mechanism: next.mechanism,
+            reason: next.degradationReason ?? 'the entry recorded no reason',
+            at: next.verifiedAt,
+        });
+    }
+    return downgrades;
+}

package/packages/cli/dist/policy/core/decision-record.js

@@ -16,12 +16,86 @@
  * - every evidence kind the policy requires must be present;
  * - a policy that redacts must not be recorded with unredacted diagnostics;
  * - the timestamp is supplied by the caller and must be an ISO-8601 date-time
- *   with seconds and an explicit zone (`ISO_8601` below; a bare date is
+ *   with seconds and an explicit zone (`ISO_8601` in `./validation.ts`, which
+ *   every shape recording an observation time reads; a bare date is
  *   refused) — no clock here.
  *
  * Each rule is one test in `packages/cli/test/policy-declaration.test.ts`
  * under "validating a decision record".
  *
+ * 🔴 EVERY field of the input is read through `carriesField`/`ownField`
+ * (`./validation.ts`) — own and enumerable, the set `Object.keys` walks — and
+ * never off the record directly. Presence and value travel through the same
+ * predicate: `'qualifier' in value` was the load-bearing half of this defect,
+ * because `unknownKeys` judges the same record by `Object.keys` while the reads
+ * walked the prototype chain, so the closed-shape check and the field reads
+ * disagreed about what the record contained — with the reads being the wider of
+ * the two, which is the direction that passes. A decision record is the
+ * artifact a later reader audits, and the shape that made this worth fixing
+ * before it had a caller is a record whose verdict qualifier is only inherited:
+ * it validates as qualified, and what it then writes out is `{"outcome":
+ * "allow","reason":…}` — the reason survives, the QUALIFIER is what is lost,
+ * which is exactly the silent pass an `UNSUPPORTED` capability state exists to
+ * prevent. Held over every reading site in this module, in both shapes —
+ * inherited, and own but not enumerable — in
+ * `packages/cli/test/policy-declaration.test.ts` › "refuses an UNSUPPORTED
+ * record whose verdict qualifier is %s, because what it writes out is a silent
+ * pass", with the other direction held by › "still accepts a record whose every
+ * field is defined through Object.defineProperty as own and enumerable". The
+ * `%s` is the name as the `it.each` case DECLARES it; quoting one expanded case
+ * gives a pointer no grep lands on.
+ *
+ * 🔴 And an unnarrowed outside value reaches a MESSAGE only through `quote`
+ * (`./validation.ts`), never through bare `String` or `JSON.stringify`.
+ * Two qualifications, because an earlier version of this sentence claimed more
+ * than the file delivers. First, `operation` and `capabilityState` are still
+ * interpolated bare into messages, safely: `member` has narrowed each to its
+ * closed vocabulary before the message is built. Second — and this is the part
+ * the sentence used to hide — a `Problem`'s **`field`** is not a message and is
+ * not escaped: `unknownKeys` (`./validation.ts`) puts the outside key name
+ * there verbatim, and `./declaration.ts` › `definePolicy` renders a report as
+ * `${field}: ${message}`, so an unknown key whose NAME carries a newline still
+ * forges a line. Escaping a `field` would break it as the machine-readable
+ * pointer it is, so the fix belongs in the rendering; it is RP-160.
+ * Both unsafe spellings inside messages were here: a qualifier
+ * carrying a newline forged two `field:
+ * message` lines of its own in the rendered problem list — the exact shape
+ * `./declaration.ts` › `definePolicy` throws — while the neighbouring line
+ * escaped the same value; and a circular value crashed the validator with a
+ * `TypeError` where `quote` degrades. Held by ›
+ * "escapes a verdict qualifier carrying a newline, so it cannot forge a line of
+ * the refusal report" and › "refuses a record whose %s is a circular value,
+ * rather than throwing while it renders the refusal".
+ *
+ * ⚠ What this does NOT do, and the limits are stated rather than implied:
+ *
+ * - the `ok: true` value is the input object itself, not a snapshot of the
+ *   fields that were certified. Those are the same thing for a value whose
+ *   fields are plain data, which is every record `JSON.parse` can produce; they
+ *   are not the same for one carrying a live accessor, which validates on one
+ *   read and serialises from another. RP-157 owns that, for this module and
+ *   `./declaration.ts` together;
+ * - nothing here caps the cost, and the amplifier is the PROBLEM LIST rather
+ *   than the input: one `Problem` is pushed per bad entry of `observedFacts` or
+ *   `evidence`, so a parsed record carrying a million bad entries produces a
+ *   million objects. That is reachable from ordinary `JSON.parse` input. The
+ *   first version of this bullet was wrong in every clause — it said
+ *   `Array.prototype.forEach` VISITS a sparse array's holes, that
+ *   `new Array(1e7)` cost seconds and gigabytes "before the refusal", and that
+ *   the cost was unreachable from a parsed record. `forEach` SKIPS holes, a
+ *   sparse `observedFacts` is not refused at all, and the dense case is the
+ *   reachable one. Corrected rather than softened, because a stale limit sells
+ *   cover that is not there (`rules/invariants.md`, "State the limits — and
+ *   test them");
+ * - an array HOLE is consequently read by nothing, while `JSON.stringify`
+ *   writes it out as `null`: `observedFacts: [{…}, , ,]` serialises as
+ *   `[{…},null,null]` and validates. That is this module's own rule — read what
+ *   the serialisation carries — failing one level BELOW the field, which is
+ *   where this change did not look. RP-161;
+ * - `quote` itself re-throws for a value whose `JSON.stringify` and `String`
+ *   both throw. The direction is a crash, never an `ok: true`, so nothing
+ *   malformed is certified through it — RP-160.
+ *
  * ⚠ `diagnostics.redacted` is the emitter's claim, and this validator enforces
  * the claim's presence, not the property: a record marked redacted whose
  * `diagnostics.text`, `observedFacts[].value` or `evidence[].value` still
@@ -31,8 +105,8 @@
  * before it persists a record.
  */
 import { compatibilityOf, findPolicy } from './registry.js';
-import { CAPABILITY_STATES, DECISION_OUTCOMES, EVIDENCE_KINDS, OPERATIONS, VERDICT_QUALIFIERS, } from './vocabulary.js';
-import { isRecord, member, nonEmptyString, unknownKeys } from './validation.js';
+import { CAPABILITY_STATES, UNENFORCEABLE_STATES, DECISION_OUTCOMES, EVIDENCE_KINDS, OPERATIONS, VERDICT_QUALIFIERS, } from './vocabulary.js';
+import { ISO_8601, carriesField, isRecord, member, nonEmptyString, ownField, quote, unknownKeys, } from './validation.js';
 export const DECISION_RECORD_SCHEMA_VERSION = 1;
 const KEYS = [
     'schemaVersion',
@@ -48,9 +122,12 @@ const KEYS = [
     'diagnostics',
     'recordedAt',
 ];
-const NEVER_SILENT_PASS = ['UNSUPPORTED', 'INTEGRATION-FAILED'];
-/** Date, `T`, time to the second (fractions allowed), and an explicit zone. */
-const ISO_8601 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+/**
+ * Read from `./vocabulary.ts` rather than restated here: `./coverage.ts` ›
+ * `qualifierFor` answers from the same list, and a second copy is how the two
+ * come to disagree about which verdicts may pass unqualified.
+ */
+const NEVER_SILENT_PASS = UNENFORCEABLE_STATES;
 const namedPairs = (problems, field, value, keys) => {
     if (!Array.isArray(value)) {
         problems.push({ field, message: 'must be a list' });
@@ -63,7 +140,7 @@ const namedPairs = (problems, field, value, keys) => {
         }
         unknownKeys(problems, entry, keys, `${field}[${index}]`);
         for (const key of keys)
-            nonEmptyString(problems, `${field}[${index}].${key}`, entry[key]);
+            nonEmptyString(problems, `${field}[${index}].${key}`, ownField(entry, key));
     });
 };
 const checkVerdict = (problems, value, capabilityState) => {
@@ -72,22 +149,23 @@ const checkVerdict = (problems, value, capabilityState) => {
         return;
     }
     unknownKeys(problems, value, ['outcome', 'qualifier', 'reason'], 'verdict');
-    member(problems, 'verdict.outcome', value.outcome, DECISION_OUTCOMES);
-    const qualified = 'qualifier' in value;
-    if (qualified) {
-        member(problems, 'verdict.qualifier', value.qualifier, VERDICT_QUALIFIERS);
-        if (typeof value.reason !== 'string' || value.reason.trim() === '') {
+    member(problems, 'verdict.outcome', ownField(value, 'outcome'), DECISION_OUTCOMES);
+    const qualifier = ownField(value, 'qualifier');
+    const reason = ownField(value, 'reason');
+    if (carriesField(value, 'qualifier')) {
+        member(problems, 'verdict.qualifier', qualifier, VERDICT_QUALIFIERS);
+        if (typeof reason !== 'string' || reason.trim() === '') {
             problems.push({
                 field: 'verdict.reason',
-                message: `a ${String(value.qualifier)} verdict must say why`,
+                message: `a ${quote(qualifier)} verdict must say why`,
             });
         }
     }
-    else if ('reason' in value && typeof value.reason !== 'string') {
+    else if (carriesField(value, 'reason') && typeof reason !== 'string') {
         problems.push({ field: 'verdict.reason', message: 'must be a string when present' });
     }
     if (capabilityState !== null && NEVER_SILENT_PASS.includes(capabilityState)) {
-        if (value.qualifier !== 'UNVERIFIABLE') {
+        if (qualifier !== 'UNVERIFIABLE') {
             problems.push({
                 field: 'verdict.qualifier',
                 message: `capabilityState ${capabilityState} never yields a silent pass: ` +
@@ -108,10 +186,11 @@ const checkEvidence = (problems, value, required) => {
             return;
         }
         unknownKeys(problems, entry, ['kind', 'value'], `evidence[${index}]`);
-        if (member(problems, `evidence[${index}].kind`, entry.kind, EVIDENCE_KINDS)) {
-            present.add(entry.kind);
+        const kind = ownField(entry, 'kind');
+        if (member(problems, `evidence[${index}].kind`, kind, EVIDENCE_KINDS)) {
+            present.add(kind);
         }
-        nonEmptyString(problems, `evidence[${index}].value`, entry.value);
+        nonEmptyString(problems, `evidence[${index}].value`, ownField(entry, 'value'));
     });
     for (const kind of required) {
         if (!present.has(kind)) {
@@ -125,16 +204,17 @@ const checkDiagnostics = (problems, value, mustRedact) => {
         return;
     }
     unknownKeys(problems, value, ['redacted', 'text'], 'diagnostics');
-    if (typeof value.redacted !== 'boolean') {
+    const redacted = ownField(value, 'redacted');
+    if (typeof redacted !== 'boolean') {
         problems.push({ field: 'diagnostics.redacted', message: 'must be a boolean' });
     }
-    else if (mustRedact && !value.redacted) {
+    else if (mustRedact && !redacted) {
         problems.push({
             field: 'diagnostics.redacted',
             message: 'the policy redacts matched values, so its diagnostics must be recorded redacted',
         });
     }
-    if (typeof value.text !== 'string') {
+    if (typeof ownField(value, 'text') !== 'string') {
         problems.push({ field: 'diagnostics.text', message: 'must be a string' });
     }
 };
@@ -145,54 +225,60 @@ export function validateDecisionRecord(input) {
     }
     const problems = [];
     unknownKeys(problems, input, KEYS);
-    if (input.schemaVersion !== DECISION_RECORD_SCHEMA_VERSION) {
+    const schemaVersion = ownField(input, 'schemaVersion');
+    if (schemaVersion !== DECISION_RECORD_SCHEMA_VERSION) {
         problems.push({
             field: 'schemaVersion',
-            message: `must be ${DECISION_RECORD_SCHEMA_VERSION}, got ${String(input.schemaVersion)}`,
+            message: `must be ${DECISION_RECORD_SCHEMA_VERSION}, got ${quote(schemaVersion)}`,
         });
     }
-    const policy = typeof input.policyId === 'string' ? findPolicy(input.policyId) : null;
+    const policyId = ownField(input, 'policyId');
+    const policyVersion = ownField(input, 'policyVersion');
+    const policy = typeof policyId === 'string' ? findPolicy(policyId) : null;
     if (policy === null) {
         problems.push({
             field: 'policyId',
-            message: `${JSON.stringify(input.policyId)} is not a registered policy`,
+            message: `${quote(policyId)} is not a registered policy`,
         });
     }
-    else if (typeof input.policyVersion === 'string') {
-        const compatibility = compatibilityOf(policy.policyId, input.policyVersion);
+    else if (typeof policyVersion === 'string') {
+        const compatibility = compatibilityOf(policy.policyId, policyVersion);
         if (compatibility !== 'compatible') {
             problems.push({
                 field: 'policyVersion',
-                message: `${JSON.stringify(input.policyVersion)} is ${compatibility} with ${policy.policyId} ${policy.policyVersion}`,
+                message: `${quote(policyVersion)} is ${compatibility} with ${policy.policyId} ${policy.policyVersion}`,
             });
         }
     }
     else {
-        nonEmptyString(problems, 'policyVersion', input.policyVersion);
+        nonEmptyString(problems, 'policyVersion', policyVersion);
     }
-    nonEmptyString(problems, 'harness', input.harness);
-    if (member(problems, 'operation', input.operation, OPERATIONS) && policy !== null) {
-        if (!policy.operations.includes(input.operation)) {
+    nonEmptyString(problems, 'harness', ownField(input, 'harness'));
+    const operation = ownField(input, 'operation');
+    if (member(problems, 'operation', operation, OPERATIONS) && policy !== null) {
+        if (!policy.operations.includes(operation)) {
             problems.push({
                 field: 'operation',
-                message: `${policy.policyId} does not apply to ${input.operation}`,
+                message: `${policy.policyId} does not apply to ${operation}`,
             });
         }
     }
-    const capabilityState = member(problems, 'capabilityState', input.capabilityState, CAPABILITY_STATES)
-        ? input.capabilityState
+    const state = ownField(input, 'capabilityState');
+    const capabilityState = member(problems, 'capabilityState', state, CAPABILITY_STATES)
+        ? state
         : null;
-    namedPairs(problems, 'observedFacts', input.observedFacts, ['name', 'value']);
-    checkVerdict(problems, input.verdict, capabilityState);
-    checkEvidence(problems, input.evidence, policy?.requiredEvidence ?? []);
-    nonEmptyString(problems, 'artifactVersion', input.artifactVersion);
-    checkDiagnostics(problems, input.diagnostics, policy !== null && policy.redaction !== 'none');
-    if (typeof input.recordedAt !== 'string' ||
-        !ISO_8601.test(input.recordedAt) ||
-        Number.isNaN(Date.parse(input.recordedAt))) {
+    namedPairs(problems, 'observedFacts', ownField(input, 'observedFacts'), ['name', 'value']);
+    checkVerdict(problems, ownField(input, 'verdict'), capabilityState);
+    checkEvidence(problems, ownField(input, 'evidence'), policy?.requiredEvidence ?? []);
+    nonEmptyString(problems, 'artifactVersion', ownField(input, 'artifactVersion'));
+    checkDiagnostics(problems, ownField(input, 'diagnostics'), policy !== null && policy.redaction !== 'none');
+    const recordedAt = ownField(input, 'recordedAt');
+    if (typeof recordedAt !== 'string' ||
+        !ISO_8601.test(recordedAt) ||
+        Number.isNaN(Date.parse(recordedAt))) {
         problems.push({
             field: 'recordedAt',
-            message: `must be an ISO-8601 date-time with seconds and an explicit zone, got ${JSON.stringify(input.recordedAt)}`,
+            message: `must be an ISO-8601 date-time with seconds and an explicit zone, got ${quote(recordedAt)}`,
         });
     }
     if (problems.length > 0)

package/packages/cli/dist/policy/core/declaration.js

@@ -12,10 +12,51 @@
  * The shape is closed: a field this interface does not name is refused, so a
  * field added by mistake cannot travel unnoticed into a record somebody later
  * audits. Every enumerated field draws from `./vocabulary.ts`.
+ *
+ * 🔴 `validateDeclaration` reads every field of its input through `ownField`
+ * (`./validation.ts`) — own and enumerable, the set `Object.keys` walks — and
+ * never off the record directly. `unknownKeys` on the line above already judges
+ * the record by `Object.keys`, so a wider read made the closed-shape check and
+ * the field reads disagree about what the record contains, with the reads being
+ * the wider of the two — the direction that passes. The consequence here is one
+ * step worse than in `./decision-record.ts`, because this validator's answer is
+ * kept: `definePolicy` copies the validated declaration by spread, and a spread
+ * copies own-enumerable keys only. So a declaration whose `tier` and `redaction`
+ * were only inherited used to be accepted and then FROZEN into the registry
+ * with no `tier` key and no `redaction` key at all — reading either yields
+ * `undefined` — a malformed entry produced by the function whose whole job is to
+ * refuse malformed ones. Held over all fifteen fields, in both shapes (inherited,
+ * and own but not enumerable), in `packages/cli/test/policy-declaration.test.ts`
+ * › "refuses a declaration whose %s is %s, because the declaration it writes out
+ * carries no such field" and, for the frozen-entry consequence, › "refuses a
+ * declaration whose tier is %s, rather than freezing an entry with no tier at
+ * all". The `%s` are the names as the `it.each` cases DECLARE them — quoting an
+ * expanded case instead is a pointer no grep lands on, which is what
+ * `test/template/evidence-pointers.test.ts` treats as a wildcard and what
+ * `rules/invariants.md` means by "the test's whole name".
+ *
+ * ⚠ What this does NOT do: `validateDeclaration` returns the input object
+ * itself (`input as unknown as PolicyDeclaration`), so what a caller gets back
+ * is the record it passed in, not a snapshot of the fields that were certified.
+ * Those are the same thing for a value whose fields are plain DATA, which is
+ * every declaration `JSON.parse` can produce; they are not the same for one
+ * carrying a live accessor. **An object literal is not the line** — a literal
+ * can carry a getter, and an earlier version of this sentence put literals on
+ * the safe side, which named the one shape that reaches the gap as the shape
+ * that avoids it. Here the consequence is kept rather than merely returned:
+ * `definePolicy` spreads the validated value, so a getter validated on read 1
+ * is FROZEN into the registry from read 2. That gap is RP-157, and
+ * `./decision-record.ts` states the identical limit at its own return.
  */
 import { AUTONOMY_TIERS, DECISION_OUTCOMES, ENFORCEMENT_TIMINGS, EVIDENCE_KINDS, FAILURE_SEMANTICS, HARNESS_CAPABILITIES, LIFECYCLE_STATES, OPERATIONS, REDACTION_RULES, } from './vocabulary.js';
-import { isRecord, matching, member, members, nonEmptyString, unknownKeys } from './validation.js';
-const KEYS = [
+import { isRecord, matching, member, members, nonEmptyString, ownField, unknownKeys, } from './validation.js';
+/**
+ * The closed set of fields a declaration may carry — exported so a test can
+ * check the fixture against THIS list by name rather than by counting it.
+ * A count agrees with a set that has drifted; `rules/invariants.md`, "One
+ * mechanism, one implementation".
+ */
+export const KEYS = [
     'policyId',
     'policyVersion',
     'lifecycle',
@@ -41,23 +82,23 @@ export function validateDeclaration(input) {
     }
     const problems = [];
     unknownKeys(problems, input, KEYS);
-    matching(problems, 'policyId', input.policyId, KEBAB_CASE, 'kebab-case');
-    matching(problems, 'policyVersion', input.policyVersion, POLICY_VERSION, 'MAJOR.MINOR');
-    member(problems, 'lifecycle', input.lifecycle, LIFECYCLE_STATES);
-    nonEmptyString(problems, 'invariant', input.invariant);
-    member(problems, 'tier', input.tier, AUTONOMY_TIERS);
-    members(problems, 'operations', input.operations, OPERATIONS, { nonEmpty: true });
-    member(problems, 'timing', input.timing, ENFORCEMENT_TIMINGS);
-    member(problems, 'requiredCapability', input.requiredCapability, HARNESS_CAPABILITIES);
-    matching(problems, 'mechanism', input.mechanism, KEBAB_CASE, 'kebab-case');
-    members(problems, 'outcomes', input.outcomes, DECISION_OUTCOMES, { nonEmpty: true });
-    member(problems, 'onInternalError', input.onInternalError, FAILURE_SEMANTICS);
-    member(problems, 'onUnreadableInput', input.onUnreadableInput, FAILURE_SEMANTICS);
-    members(problems, 'requiredEvidence', input.requiredEvidence, EVIDENCE_KINDS, {
+    matching(problems, 'policyId', ownField(input, 'policyId'), KEBAB_CASE, 'kebab-case');
+    matching(problems, 'policyVersion', ownField(input, 'policyVersion'), POLICY_VERSION, 'MAJOR.MINOR');
+    member(problems, 'lifecycle', ownField(input, 'lifecycle'), LIFECYCLE_STATES);
+    nonEmptyString(problems, 'invariant', ownField(input, 'invariant'));
+    member(problems, 'tier', ownField(input, 'tier'), AUTONOMY_TIERS);
+    members(problems, 'operations', ownField(input, 'operations'), OPERATIONS, { nonEmpty: true });
+    member(problems, 'timing', ownField(input, 'timing'), ENFORCEMENT_TIMINGS);
+    member(problems, 'requiredCapability', ownField(input, 'requiredCapability'), HARNESS_CAPABILITIES);
+    matching(problems, 'mechanism', ownField(input, 'mechanism'), KEBAB_CASE, 'kebab-case');
+    members(problems, 'outcomes', ownField(input, 'outcomes'), DECISION_OUTCOMES, { nonEmpty: true });
+    member(problems, 'onInternalError', ownField(input, 'onInternalError'), FAILURE_SEMANTICS);
+    member(problems, 'onUnreadableInput', ownField(input, 'onUnreadableInput'), FAILURE_SEMANTICS);
+    members(problems, 'requiredEvidence', ownField(input, 'requiredEvidence'), EVIDENCE_KINDS, {
         nonEmpty: false,
     });
-    member(problems, 'redaction', input.redaction, REDACTION_RULES);
-    nonEmptyString(problems, 'statedIn', input.statedIn);
+    member(problems, 'redaction', ownField(input, 'redaction'), REDACTION_RULES);
+    nonEmptyString(problems, 'statedIn', ownField(input, 'statedIn'));
     if (problems.length > 0)
         return { ok: false, problems };
     // Every field above was checked against the shape, so the narrowing is earned