rea-agents 2.4.0 → 2.5.0

package/dist/domain/reconstructionReadinessJourneyFindings.js

@@ -0,0 +1,193 @@
+import { addMissingEvidenceFindings, readinessFinding as finding, } from "./reconstructionReadinessFindingHelpers.js";
+import { readinessStageIdSchema, } from "./reconstructionReadinessSchemas.js";
+export const READINESS_REQUIRED_CHECKS = {
+    "discover-classify": [
+        "target-free-start",
+        "artifact-inventory",
+        "compatible-workflow-selected",
+        "limits-visible",
+    ],
+    "diagnose-environment": [
+        "broken-runtime-distinguished",
+        "version-skew-detected",
+        "revision-changed-after-recovery",
+    ],
+    "acquire-authority": [
+        "missing-scope-reported",
+        "narrow-grant-resumed",
+        "expansion-reprompted",
+        "denial-launched-nothing",
+    ],
+    "static-analysis": [
+        "native-routed",
+        "javascript-routed",
+        "unknowns-preserved",
+    ],
+    "reactive-scenarios": [
+        "predicate-driven",
+        "descendant-settled",
+        "electron-correlated",
+        "cancel-cleanup-preserved-evidence",
+    ],
+    "compare-authority-candidate": [
+        "partial-order-accepted",
+        "divergence-localized",
+        "incomplete-is-unknown",
+    ],
+    "preserve-contradictions": [
+        "record-and-continue",
+        "affected-equivalence-blocked",
+        "unaffected-comparison-continued",
+    ],
+    "verify-reconstruction-closure": [
+        "incomplete-detected",
+        "incremental-verifier-closure",
+        "delegation-rejected",
+    ],
+    "export-replay": [
+        "cli-mcp-parity",
+        "failure-status-parity",
+        "deterministic-replay",
+        "tamper-detected",
+        "stale-input-detected",
+    ],
+};
+export const READINESS_STAGE_IDS = readinessStageIdSchema.options;
+export const readinessJourneyFindings = (input, evidenceIds) => [
+    ...identityFindings(input),
+    ...fixtureFindings(input),
+    ...stageFindings(input, evidenceIds),
+    ...capabilityFindings(input),
+    ...workflowFindings(input),
+    ...authorityFindings(input),
+    ...outcomeFindings(input, evidenceIds),
+];
+const identityFindings = (input) => {
+    const findings = [];
+    if (!input.identity.versions.some(({ state }) => state === "stale"))
+        findings.push(finding("version-skew-observation-missing", "diagnose-environment", "fail", "The journey did not preserve a stale version observation."));
+    if (!input.identity.versions.some(({ state }) => state === "current"))
+        findings.push(finding("corrected-version-observation-missing", "diagnose-environment", "fail", "The journey did not preserve corrected current version state."));
+    if (!input.identity.providers.some(({ state }) => state === "broken-host"))
+        findings.push(finding("broken-host-observation-missing", "diagnose-environment", "fail", "The journey did not distinguish a broken host dependency."));
+    return findings;
+};
+const fixtureFindings = (input) => {
+    const requiredKinds = [
+        "native",
+        "javascript-cli",
+        "electron",
+        "incomplete-reconstruction",
+        "broken-runtime",
+    ];
+    return requiredKinds.flatMap((kind) => input.fixtures.some(({ kind: fixtureKind }) => fixtureKind === kind)
+        ? []
+        : [
+            finding("representative-fixture-missing", "discover-classify", "fail", `The required ${kind} fixture is missing.`),
+        ]);
+};
+const stageFindings = (input, evidenceIds) => {
+    const findings = [];
+    for (const stageId of READINESS_STAGE_IDS) {
+        const matching = input.stages.filter(({ stage_id: id }) => id === stageId);
+        if (matching.length !== 1) {
+            findings.push(finding("stage-cardinality", stageId, "fail", `Expected exactly one ${stageId} stage; observed ${String(matching.length)}.`));
+            continue;
+        }
+        const stage = matching[0];
+        if (stage === undefined)
+            continue;
+        if (!stage.required)
+            findings.push(finding("required-stage-disabled", stageId, "fail", "The public conformance journey requires this stage."));
+        const checks = new Map(stage.checks.map((check) => [check.check_id, check]));
+        if (checks.size !== stage.checks.length)
+            findings.push(finding("duplicate-stage-check", stageId, "fail", "Stage check IDs must be unique."));
+        for (const checkId of READINESS_REQUIRED_CHECKS[stageId]) {
+            const check = checks.get(checkId);
+            if (check === undefined) {
+                findings.push(finding("missing-stage-check", stageId, "fail", `Required conformance check is missing: ${checkId}.`));
+                continue;
+            }
+            if (check.status !== "pass")
+                findings.push(finding("stage-check-not-pass", stageId, check.status === "fail" ? "fail" : "unknown", `${checkId} is ${check.status}: ${check.detail}`, check.evidence_ids));
+            if (check.evidence_ids.length === 0)
+                findings.push(finding("stage-check-evidence-missing", stageId, "unknown", `${checkId} has no attributable Evidence.`));
+            addMissingEvidenceFindings(findings, stageId, [...stage.evidence_ids, ...check.evidence_ids], evidenceIds);
+        }
+    }
+    return findings;
+};
+const capabilityFindings = (input) => input.capabilities.flatMap((capability) => {
+    const findings = [];
+    if (capability.bounded && capability.limits.length === 0)
+        findings.push(finding("bounded-limit-hidden", "discover-classify", "fail", `${capability.capability_id} is bounded but declares no exact limits.`));
+    if (!capability.available && capability.unavailable_reason === null)
+        findings.push(finding("unavailable-reason-missing", "discover-classify", "unknown", `${capability.capability_id} is unavailable without an actionable reason.`));
+    return findings;
+});
+const workflowFindings = (input) => {
+    const findings = [];
+    for (const fixture of input.fixtures) {
+        const selected = input.workflow_candidates.filter(({ fixture_id: fixtureId, selected: isSelected }) => fixtureId === fixture.fixture_id && isSelected);
+        if (selected.length !== 1 || selected[0]?.compatibility !== "compatible")
+            findings.push(finding("compatible-workflow-not-selected", "discover-classify", "fail", `${fixture.fixture_id} does not have exactly one compatible selected workflow.`));
+    }
+    for (const candidate of input.workflow_candidates)
+        if (candidate.invoked && candidate.compatibility !== "compatible")
+            findings.push(finding("incompatible-provider-invoked", "static-analysis", "fail", `${candidate.workflow_id} was invoked despite ${candidate.compatibility} routing.`));
+    return findings;
+};
+const authorityFindings = (input) => {
+    const deniedScopes = new Set(input.grants
+        .filter(({ decision }) => ["denied", "cancelled"].includes(decision))
+        .map(({ scope }) => scope));
+    const recoveredScopes = new Set(input.grants
+        .filter(({ decision }) => decision === "granted")
+        .map(({ scope }) => scope));
+    return [...deniedScopes].some((scope) => recoveredScopes.has(scope))
+        ? []
+        : [
+            finding("narrow-authority-recovery-missing", "acquire-authority", "fail", "No denied or cancelled scope was later recovered by a narrow grant."),
+        ];
+};
+const outcomeFindings = (input, evidenceIds) => {
+    const findings = [];
+    const parity = new Map();
+    for (const outcome of input.operation_outcomes) {
+        const expectedCliExit = outcome.expected_success ? 0 : 1;
+        if (outcome.surface === "cli" &&
+            (outcome.cli_exit_code === null ||
+                (expectedCliExit === 0
+                    ? outcome.cli_exit_code !== 0
+                    : outcome.cli_exit_code === 0)))
+            findings.push(finding("cli-status-mismatch", "export-replay", "fail", `${outcome.operation} CLI process status contradicts its structured outcome.`, outcome.evidence_ids));
+        if (outcome.surface === "mcp" &&
+            outcome.mcp_status !==
+                (outcome.expected_success ? "success" : "non-success"))
+            findings.push(finding("mcp-status-mismatch", "export-replay", "fail", `${outcome.operation} MCP status contradicts its structured outcome.`, outcome.evidence_ids));
+        const key = `${outcome.operation}:${outcome.call_kind}:${String(outcome.expected_success)}`;
+        parity.set(key, new Set([...(parity.get(key) ?? []), outcome.surface]));
+        addMissingEvidenceFindings(findings, "export-replay", outcome.evidence_ids, evidenceIds);
+    }
+    for (const [key, surfaces] of parity)
+        if (surfaces.size !== 2)
+            findings.push(finding("surface-parity-missing", "export-replay", "fail", `CLI/MCP outcome pair is incomplete: ${key}.`));
+    for (const [key, outcomes] of groupedOutcomes(input)) {
+        const cli = outcomes.find(({ surface }) => surface === "cli");
+        const mcp = outcomes.find(({ surface }) => surface === "mcp");
+        if (cli !== undefined &&
+            mcp !== undefined &&
+            (cli.expected_success !== mcp.expected_success ||
+                cli.error_code !== mcp.error_code))
+            findings.push(finding("surface-semantic-drift", "export-replay", "fail", `CLI/MCP structured outcomes disagree: ${key}.`, [...cli.evidence_ids, ...mcp.evidence_ids]));
+    }
+    return findings;
+};
+const groupedOutcomes = (input) => {
+    const grouped = new Map();
+    for (const outcome of input.operation_outcomes) {
+        const key = `${outcome.operation}:${outcome.call_kind}`;
+        grouped.set(key, [...(grouped.get(key) ?? []), outcome]);
+    }
+    return grouped;
+};

package/dist/domain/reconstructionReadinessSchemas.js

@@ -0,0 +1,240 @@
+import { z } from "zod";
+import { evidenceBundleSchema } from "./evidenceBundle.js";
+import { reconstructionObligationLedgerSchema } from "./reconstructionObligationLedgerSchemas.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const stableIdSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._:/-]{0,199}$/u);
+const boundedTextSchema = z.string().trim().min(1).max(4_096);
+export const readinessStatusSchema = z.enum([
+    "pass",
+    "fail",
+    "unknown",
+    "unsupported",
+    "truncated",
+    "skipped",
+]);
+export const readinessStageIdSchema = z.enum([
+    "discover-classify",
+    "diagnose-environment",
+    "acquire-authority",
+    "static-analysis",
+    "reactive-scenarios",
+    "compare-authority-candidate",
+    "preserve-contradictions",
+    "verify-reconstruction-closure",
+    "export-replay",
+]);
+const versionObservationSchema = z.strictObject({
+    component: stableIdSchema,
+    version: boundedTextSchema.nullable(),
+    digest: digestSchema.nullable(),
+    state: z.enum(["current", "stale", "unavailable"]),
+    remediation: boundedTextSchema.nullable(),
+});
+const providerIdentitySchema = z.strictObject({
+    provider_id: stableIdSchema,
+    version: boundedTextSchema.nullable(),
+    digest: digestSchema.nullable(),
+    state: z.enum(["available", "unavailable", "incompatible", "broken-host"]),
+    reason_code: stableIdSchema.nullable(),
+});
+const limitSchema = z.strictObject({
+    name: stableIdSchema,
+    value: z.number().finite().nonnegative(),
+    unit: z.enum(["count", "bytes", "milliseconds", "ratio"]),
+});
+const capabilitySchema = z.strictObject({
+    capability_id: stableIdSchema,
+    available: z.boolean(),
+    bounded: z.boolean(),
+    side_effect: z.enum([
+        "none",
+        "reads-target",
+        "launches-process",
+        "writes-workspace",
+        "network-observation",
+    ]),
+    authority_scopes: z.array(stableIdSchema).max(100),
+    limits: z.array(limitSchema).max(100),
+    unavailable_reason: boundedTextSchema.nullable(),
+});
+const fixtureSchema = z.strictObject({
+    fixture_id: stableIdSchema,
+    kind: z.enum([
+        "native",
+        "javascript-cli",
+        "electron",
+        "incomplete-reconstruction",
+        "broken-runtime",
+    ]),
+    artifact_sha256: digestSchema,
+    environment_id: stableIdSchema,
+    deliberate_faults: z.array(stableIdSchema).min(1).max(100),
+});
+const workflowCandidateSchema = z.strictObject({
+    fixture_id: stableIdSchema,
+    workflow_id: stableIdSchema,
+    provider_id: stableIdSchema.nullable(),
+    selected: z.boolean(),
+    invoked: z.boolean(),
+    compatibility: z.enum(["compatible", "incompatible", "unavailable"]),
+    reason_code: stableIdSchema,
+});
+const grantSchema = z.strictObject({
+    grant_id: stableIdSchema,
+    scope: stableIdSchema,
+    decision: z.enum(["granted", "denied", "cancelled", "restart-required"]),
+    launched_process: z.boolean(),
+    evidence_ids: z.array(evidenceIdSchema).max(100),
+});
+const comparisonSchema = z.strictObject({
+    comparison_id: stableIdSchema,
+    verdict: z.enum(["equivalent", "different", "unknown"]),
+    schedule_semantics: z.enum(["total-order", "partial-order", "finite-traces"]),
+    concurrent: z.boolean(),
+    truncated: z.boolean(),
+    unavailable_authority: z.boolean(),
+    unstable: z.boolean(),
+    deliberate_divergence_ref: boundedTextSchema.nullable(),
+    divergence_refs: z.array(boundedTextSchema).max(100),
+    contradiction_ids: z.array(stableIdSchema).max(100),
+    evidence_ids: z.array(evidenceIdSchema).min(1).max(1_000),
+});
+const contradictionSchema = z.strictObject({
+    contradiction_id: stableIdSchema,
+    declared_sha256: digestSchema,
+    observed_sha256: digestSchema,
+    policy: z.literal("record-and-continue"),
+    affected_comparison_ids: z.array(stableIdSchema).min(1).max(100),
+    evidence_ids: z.array(evidenceIdSchema).min(2).max(100),
+});
+const operationOutcomeSchema = z.strictObject({
+    sequence: z.number().int().min(0),
+    operation: stableIdSchema,
+    surface: z.enum(["cli", "mcp"]),
+    call_kind: z.enum([
+        "valid",
+        "malformed",
+        "over-limit",
+        "incompatible-provider",
+        "setup",
+        "permission",
+        "operation",
+    ]),
+    expected_success: z.boolean(),
+    cli_exit_code: z.number().int().min(0).nullable(),
+    mcp_status: z.enum(["success", "non-success"]).nullable(),
+    error_code: stableIdSchema.nullable(),
+    recovered: z.boolean(),
+    evidence_ids: z.array(evidenceIdSchema).max(100),
+});
+const cleanupSchema = z.strictObject({
+    run_id: stableIdSchema,
+    cancelled: z.boolean(),
+    owned_resources_remaining: z.number().int().min(0),
+    diagnostic_evidence_ids: z.array(evidenceIdSchema).max(100),
+});
+const closureObservationSchema = z.strictObject({
+    sequence: z.number().int().min(0),
+    ledger_digest: digestSchema,
+    status: z.enum(["ready", "open", "failed", "unknown"]),
+    required_open: z.number().int().min(0),
+    newly_verified_obligation_ids: z.array(stableIdSchema).max(10_000),
+    evidence_ids: z.array(evidenceIdSchema).min(1).max(1_000),
+});
+const delegationCheckSchema = z.strictObject({
+    candidate_id: stableIdSchema,
+    delegates_to_authority: z.boolean(),
+    evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+});
+const stageCheckSchema = z.strictObject({
+    check_id: stableIdSchema,
+    status: readinessStatusSchema,
+    detail: boundedTextSchema,
+    evidence_ids: z.array(evidenceIdSchema).max(100),
+});
+const stageSchema = z.strictObject({
+    stage_id: readinessStageIdSchema,
+    required: z.boolean(),
+    status: readinessStatusSchema,
+    capability_issue: stableIdSchema.nullable(),
+    next_action: boundedTextSchema.nullable(),
+    evidence_ids: z.array(evidenceIdSchema).max(1_000),
+    checks: z.array(stageCheckSchema).max(100),
+});
+const replaySchema = z.strictObject({
+    expected_source_digest: digestSchema.nullable(),
+    deterministic: z.boolean(),
+    tamper_detected: z.boolean(),
+    stale_input_detected: z.boolean(),
+    evidence_ids: z.array(evidenceIdSchema).max(100),
+});
+export const reconstructionReadinessInputSchema = z.strictObject({
+    schema_version: z.literal(1),
+    identity: z.strictObject({
+        cli_version: boundedTextSchema,
+        server_version: boundedTextSchema,
+        catalog_digest: digestSchema,
+        skill_digest: digestSchema.nullable(),
+        versions: z.array(versionObservationSchema).min(1).max(100),
+        providers: z.array(providerIdentitySchema).max(100),
+    }),
+    client: z.strictObject({
+        name: boundedTextSchema,
+        version: boundedTextSchema,
+        negotiated_capabilities: z.array(stableIdSchema).max(100),
+    }),
+    capabilities: z.array(capabilitySchema).min(1).max(1_000),
+    fixtures: z.array(fixtureSchema).min(1).max(100),
+    workflow_candidates: z.array(workflowCandidateSchema).min(1).max(1_000),
+    grants: z.array(grantSchema).max(1_000),
+    evidence_bundle: evidenceBundleSchema,
+    comparisons: z.array(comparisonSchema).max(1_000),
+    contradictions: z.array(contradictionSchema).max(1_000),
+    obligation_ledger: reconstructionObligationLedgerSchema,
+    operation_outcomes: z.array(operationOutcomeSchema).max(10_000),
+    cleanup: z.array(cleanupSchema).max(1_000),
+    closure_history: z.array(closureObservationSchema).min(2).max(1_000),
+    delegation_checks: z.array(delegationCheckSchema).min(1).max(1_000),
+    replay: replaySchema,
+    stages: z.array(stageSchema).max(20),
+});
+const findingSchema = z.strictObject({
+    code: stableIdSchema,
+    stage_id: readinessStageIdSchema,
+    status: z.enum(["fail", "unknown"]),
+    detail: boundedTextSchema,
+    evidence_ids: z.array(evidenceIdSchema).max(100),
+});
+export const reconstructionReadinessReportSchema = z.strictObject({
+    schema: z.literal("ReconstructionReadinessReport"),
+    schema_version: z.literal(1),
+    report_id: z.string().regex(/^rr_[a-f0-9]{64}$/u),
+    source_digest: digestSchema,
+    report_digest: digestSchema,
+    status: readinessStatusSchema,
+    summary: z.strictObject({
+        stages: z.number().int().min(0),
+        required_stages: z.number().int().min(0),
+        passed_required_stages: z.number().int().min(0),
+        findings: z.number().int().min(0),
+        failed_findings: z.number().int().min(0),
+        unknown_findings: z.number().int().min(0),
+    }),
+    metrics: z.strictObject({
+        first_valid_workflow_selection_rate: z.number().min(0).max(1),
+        malformed_or_over_limit_call_rate: z.number().min(0).max(1),
+        incompatible_provider_invocations: z.number().int().min(0),
+        failed_calls_before_prerequisites: z.number().int().min(0),
+        recovery_rate: z.number().min(0).max(1),
+        divergence_localization_precision: z.number().min(0).max(1),
+        false_equivalence_count: z.number().int().min(0),
+        unowned_obligation_count: z.number().int().min(0),
+        cleanup_leak_count: z.number().int().min(0),
+        nondeterministic_replay_count: z.number().int().min(0),
+    }),
+    stages: z.array(stageSchema).max(20),
+    findings: z.array(findingSchema).max(10_000),
+    evidence_links: z.array(evidenceIdSchema).max(100_000),
+    snapshot: reconstructionReadinessInputSchema,
+});