Files
rea/src/domain/completionLedgerGeneration.ts
T
felipeatpandGitHub f0da05f67f fix: emit v-mode-compatible patterns for tool schemas (#1220)
* fix: emit v-mode-compatible patterns for tool schemas

Character classes in emitted patterns carried unescaped '-', '/' and '['. Annex-B and u-mode accept them, so REA's own Zod validation (u) and every u-based validator never saw a defect, but v-mode rejects ClassSetSyntaxCharacters and Ruby rejects [^s[]]. With 6.1.0 tools/list, 117 pattern fields across 11 tools were rejected under v.

The characters are escaped as \x2d, \x2f, \x5b and \x5d rather than \-/\//\[, because oxlint --fix removes an escaped '-' inside a character class as a useless escape, so an escape-only change does not survive the pre-commit hook. \x2d-style escapes are valid under Annex B, u and v, are matched identically, and are not useless-escape candidates.

22 pattern literals in 18 files are touched; no other token changes.

* fix: replace the Zod offset pattern and guard the advertised catalog

The offset datetime site projected Zod's offset class as [ +- ], which no escape in this repository's sources can reach, so evaluate_reconstruction_coverage stayed unreachable for exactly the clients this change targets. It now uses offsetDateTimeSchema in src/domain/offsetDateTime.ts: the same accepted set with the offset class escaped as [ +\x2d ].

Adds tests/boundary/mcp/advertisedPatternsVMode.test.ts, which performs the real tools/list projection, traverses every advertised input and output schema, compiles each pattern under v, and asserts the inventory it walked so a silent traversal collapse fails instead of passing vacuously.
2026-10-09 16:20:57 +08:00

246 lines
8.4 KiB
TypeScript

import { createHash } from "node:crypto";
import canonicalize from "canonicalize";
import { z } from "zod";
import {
createEvidenceCompletionLedger,
evidenceCompletionRecordSchema,
type EvidenceCompletionLedger,
} from "./evidenceCompletionLedger.js";
import { digestSchema } from "./../domain/digests.js";
import { prefixedDigestSchema } from "./../domain/digests.js";
const identifierSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._\x2d]*$/u);
const identitySchema = z.strictObject({
id: identifierSchema,
version: z.string().min(1),
});
const environmentSchema = z.strictObject({
platform: identifierSchema,
architecture: identifierSchema,
runtime: identifierSchema,
runtime_version: z.string().min(1),
});
const scenarioSchema = z.strictObject({
id: identifierSchema,
version: z.number().int().positive(),
});
const skillDigestSchema = z.strictObject({
skill_id: identifierSchema,
sha256: digestSchema,
});
const verifierRunSchema = z
.strictObject({
run_id: z.string().uuid(),
verifier_pid: z.number().int().positive(),
parent_pid: z.number().int().nonnegative(),
process_lineage: z.discriminatedUnion("status", [
z.strictObject({
status: z.literal("verified"),
observed_at: z.iso.datetime(),
launcher_pid: z.number().int().positive(),
launcher_parent_pid: z.number().int().nonnegative(),
process_group_id: z.number().int().positive(),
descendants: z.array(
z.strictObject({
pid: z.number().int().positive(),
parent_pid: z.number().int().nonnegative(),
process_group_id: z.number().int().positive(),
}),
),
}),
z.strictObject({
status: z.literal("unavailable"),
observed_at: z.iso.datetime(),
launcher_pid: z.number().int().positive(),
launcher_parent_pid: z.number().int().nonnegative(),
process_group_id: z.number().int().positive().nullable(),
reason: z.string().min(1),
}),
]),
})
.superRefine((run, context) => {
if (run.process_lineage.launcher_pid !== run.verifier_pid)
context.addIssue({
code: "custom",
path: ["process_lineage", "launcher_pid"],
message: "Lineage launcher PID must identify the verifier process",
});
if (run.process_lineage.launcher_parent_pid !== run.parent_pid)
context.addIssue({
code: "custom",
path: ["process_lineage", "launcher_parent_pid"],
message: "Lineage parent PID must identify the verifier parent",
});
});
const reportClaimSchema = z.strictObject({
claim_id: identifierSchema,
scenario: scenarioSchema,
artifact_sha256s: z.array(digestSchema),
provider: identitySchema,
status: evidenceCompletionRecordSchema.shape.status,
evidence_ids: evidenceCompletionRecordSchema.shape.evidence_ids,
});
const completionVerifierReportObjectSchema = z.strictObject({
verifier: identitySchema,
verifier_run: verifierRunSchema,
environment: environmentSchema,
claims: z.array(reportClaimSchema).min(1),
});
/** Strict output contract implemented by completion-aware verifiers. */
export const completionVerifierReportSchema =
completionVerifierReportObjectSchema.superRefine((report, context) => {
for (const [index, claim] of report.claims.entries())
if (claim.status === "pass" && claim.artifact_sha256s.length === 0)
context.addIssue({
code: "custom",
path: ["claims", index, "artifact_sha256s"],
message: "Passing claims must commit at least one artifact digest",
});
});
export type CompletionVerifierReport = z.infer<
typeof completionVerifierReportSchema
>;
const manifestClaimSchema = reportClaimSchema.omit({
status: true,
evidence_ids: true,
});
const completionManifestObjectSchema = z.strictObject({
manifest_id: prefixedDigestSchema("ecm"),
verifier: identitySchema,
environment: environmentSchema,
skill_digests: z.array(skillDigestSchema).min(1),
claims: z.array(manifestClaimSchema).min(1),
});
type CompletionManifestValue = z.infer<typeof completionManifestObjectSchema>;
const compareIdentifiers = (left: string, right: string): number =>
left < right ? -1 : left > right ? 1 : 0;
const isSortedUnique = (values: readonly string[]): boolean =>
values.every(
(value, index) =>
index === 0 || compareIdentifiers(values[index - 1] ?? "", value) < 0,
);
const canonicalJson = (value: unknown): string => {
const serialized = canonicalize(value);
if (serialized === undefined)
throw new TypeError(
"RFC 8785 canonicalization rejected completion metadata",
);
return serialized;
};
const computeManifestId = (
manifest: Omit<CompletionManifestValue, "manifest_id">,
): string =>
`ecm_${createHash("sha256").update(canonicalJson(manifest)).digest("hex")}`;
const manifestIssues = (
manifest: CompletionManifestValue,
context: z.RefinementCtx,
): void => {
if (!isSortedUnique(manifest.claims.map(({ claim_id }) => claim_id)))
context.addIssue({
code: "custom",
path: ["claims"],
message: "Manifest claims must be sorted by unique claim ID",
});
if (!isSortedUnique(manifest.skill_digests.map(({ skill_id }) => skill_id)))
context.addIssue({
code: "custom",
path: ["skill_digests"],
message: "Skill digests must be sorted by unique skill ID",
});
for (const [index, claim] of manifest.claims.entries())
if (!isSortedUnique(claim.artifact_sha256s))
context.addIssue({
code: "custom",
path: ["claims", index, "artifact_sha256s"],
message: "Artifact digests must be sorted and unique",
});
const { manifest_id: manifestId, ...projection } = manifest;
if (computeManifestId(projection) !== manifestId)
context.addIssue({
code: "custom",
path: ["manifest_id"],
message: "Completion manifest identifier does not match its content",
});
};
/** Canonical immutable commitments for one verifier run. */
export const completionManifestSchema =
completionManifestObjectSchema.superRefine(manifestIssues);
export type CompletionManifest = z.infer<typeof completionManifestSchema>;
/** Generated completion metadata derived from a verifier report. */
export interface CompletionLedgerArtifacts {
readonly manifest: CompletionManifest;
readonly ledger: EvidenceCompletionLedger;
}
const canonicalClaims = (
claims: CompletionVerifierReport["claims"],
): CompletionVerifierReport["claims"] =>
claims
.map((claim) => ({
...claim,
artifact_sha256s: [...claim.artifact_sha256s].sort(compareIdentifiers),
evidence_ids: [...claim.evidence_ids].sort(compareIdentifiers),
}))
.sort((left, right) => compareIdentifiers(left.claim_id, right.claim_id));
/** Generate canonical manifest and ledger artifacts from live verifier output. */
export const createCompletionLedgerArtifacts = (
input: unknown,
skillDigests: readonly z.input<typeof skillDigestSchema>[],
): CompletionLedgerArtifacts => {
const report = completionVerifierReportSchema.parse(input);
const claims = canonicalClaims(report.claims);
if (!isSortedUnique(claims.map(({ claim_id }) => claim_id)))
throw new TypeError("Completion verifier claim IDs must be unique");
for (const claim of claims) {
if (!isSortedUnique(claim.artifact_sha256s))
throw new TypeError("Artifact digests must be unique per claim");
if (!isSortedUnique(claim.evidence_ids))
throw new TypeError("Evidence IDs must be unique per claim");
}
const skills = skillDigests
.map((skill) => skillDigestSchema.parse(skill))
.sort((left, right) => compareIdentifiers(left.skill_id, right.skill_id));
if (!isSortedUnique(skills.map(({ skill_id }) => skill_id)))
throw new TypeError("Completion skill IDs must be unique");
const projection = {
verifier: report.verifier,
environment: report.environment,
skill_digests: skills,
claims: claims.map(
({ status: _status, evidence_ids: _evidenceIds, ...claim }) => claim,
),
};
return {
manifest: completionManifestSchema.parse({
...projection,
manifest_id: computeManifestId(projection),
}),
ledger: createEvidenceCompletionLedger(
claims.map(({ claim_id, status, evidence_ids }) => ({
claim_id,
status,
evidence_ids,
})),
),
};
};
/** Parse generated completion commitments and reject manual tampering. */
export const parseCompletionManifest = (input: unknown): CompletionManifest =>
completionManifestSchema.parse(input);