@kontourai/flow-agents 3.12.1 → 4.1.0

package/dist/opencode/build/src/cli/validate-workflow-artifacts.js

@@ -18,6 +18,7 @@ const sidecarSchemas = {
     "critique.json": "schemas/workflow-critique.schema.json",
     "release.json": "schemas/workflow-release.schema.json",
     "learning.json": "schemas/workflow-learning.schema.json",
+    "waves.json": "schemas/workflow-waves.schema.json",
 };
 // Runtime coordination records live below a session but are not workflow
 // sidecars. Recursing into them would validate continuation-driver/state.json
@@ -386,11 +387,63 @@ function validateSidecar(file) {
                 issues.push({ path: file, message: "deploy decision requires post_deploy_checks to be planned or pass" });
         }
     }
+    if (path.basename(file) === "waves.json") {
+        validateWaves(file, value, issues);
+    }
     if (path.basename(file) === "state.json" && value && typeof value === "object" && !Array.isArray(value) && !("branch" in value)) {
         warnings.push({ path: file, message: "state.json has no branch field (legacy/pre-#289 session) — re-run `ensure-session` to backfill agent/<actor>/<slug>." });
     }
     return { issues, warnings };
 }
+// #663 slice 1: wave-result reconciliation is machine-checkable, not prose. The schema
+// (schemas/workflow-waves.schema.json) validates the shape; these semantic checks enforce the
+// cross-record arithmetic the mini schema engine cannot express: exactly one terminal status
+// record per declared worker, no undeclared reporters, reconciliation counts that match the
+// records, and a `complete` claim that is impossible while any expected worker lacks a
+// worker-landed terminal status. Missing workers must be recorded explicitly as not_reported —
+// a reconciled wave never silently absorbs a dropped worker. Enforcement here is data-level
+// validation only; stop-hook refusal of wave completion is #663 part 3 (slice 2).
+function validateWaves(file, value, issues) {
+    const waves = Array.isArray(value?.waves) ? value.waves : [];
+    waves.forEach((wave, index) => {
+        const loc = `waves.json.waves[${index}]`;
+        const expected = Array.isArray(wave?.expected_workers) ? wave.expected_workers : [];
+        const results = Array.isArray(wave?.worker_results) ? wave.worker_results : [];
+        const expectedIds = expected.map((w) => w?.worker_id).filter((id) => typeof id === "string" && id.length > 0);
+        const expectedIdSet = new Set(expectedIds);
+        if (expectedIdSet.size !== expectedIds.length)
+            issues.push({ path: file, message: `${loc}.expected_workers must declare unique worker_id values` });
+        const resultIds = results.map((r) => r?.worker_id).filter((id) => typeof id === "string" && id.length > 0);
+        const seen = new Set();
+        for (const id of resultIds) {
+            if (seen.has(id))
+                issues.push({ path: file, message: `${loc}.worker_results has more than one terminal status record for worker ${id}; each worker lands exactly one` });
+            seen.add(id);
+            if (!expectedIdSet.has(id))
+                issues.push({ path: file, message: `${loc}.worker_results records worker ${id} that is not declared in expected_workers; declare every worker in the manifest before dispatch` });
+        }
+        const reconciliation = wave?.reconciliation;
+        if (!reconciliation || typeof reconciliation !== "object" || Array.isArray(reconciliation))
+            return;
+        const expectedCount = expectedIds.length;
+        const reportedIds = new Set(results.filter((r) => ["completed", "failed", "blocked"].includes(r?.status) && expectedIdSet.has(r?.worker_id)).map((r) => r.worker_id));
+        const reportedCount = reportedIds.size;
+        if (reconciliation.expected_count !== expectedCount)
+            issues.push({ path: file, message: `${loc}.reconciliation.expected_count is ${reconciliation.expected_count} but expected_workers declares ${expectedCount}` });
+        if (reconciliation.reported_count !== reportedCount)
+            issues.push({ path: file, message: `${loc}.reconciliation.reported_count is ${reconciliation.reported_count} but ${reportedCount} of ${expectedCount} expected workers have a worker-landed terminal status (completed|failed|blocked)` });
+        const missing = expectedIds.filter((id) => !results.some((r) => r?.worker_id === id));
+        for (const id of missing)
+            issues.push({ path: file, message: `${loc} is reconciled but worker ${id} has no terminal status record; record it explicitly as not_reported — never silently absorb a missing worker` });
+        const notReported = results.filter((r) => r?.status === "not_reported" && expectedIdSet.has(r?.worker_id));
+        if (reconciliation.status === "complete" && (missing.length > 0 || notReported.length > 0 || reportedCount !== expectedCount)) {
+            issues.push({ path: file, message: `${loc}.reconciliation.status complete requires every expected worker to have a worker-landed terminal status; got ${reportedCount} of ${expectedCount} reported` });
+        }
+        if (reconciliation.status === "incomplete" && missing.length === 0 && notReported.length === 0 && reportedCount === expectedCount) {
+            issues.push({ path: file, message: `${loc}.reconciliation.status incomplete contradicts the records: all ${expectedCount} expected workers reported` });
+        }
+    });
+}
 function validateLearningCorrections(file, status, records, issues) {
     records.forEach((record, index) => {
         const correction = record?.correction;

package/dist/opencode/build/src/cli/workflow-sidecar.d.ts

@@ -27,15 +27,15 @@ export declare function validateTrustBundle(bundle: unknown): Promise<{
     available: boolean;
 }>;
 /**
- * Validate a record against the canonical hachure inquiry-record.schema.json
- * (https://kontourai.io/schemas/surface/inquiry-record.schema.json).
- * Returns `{ valid, errors, available }`. Fail-open when hachure is not installed.
+ * Validate a record against the canonical InquiryRecord schema via
+ * @kontourai/surface's `validateInquiryRecord` (symmetric to `validateTrustBundle`).
+ * Returns `{ valid, errors, available }`. Fail-open when Surface is unavailable.
  */
-export declare function validateInquiryRecord(record: unknown): {
+export declare function validateInquiryRecord(record: unknown): Promise<{
     valid: boolean;
     errors: string[];
     available: boolean;
-};
+}>;
 type SurfaceInquiry = {
     id: string;
     question: string;
@@ -91,8 +91,12 @@ type SurfaceModule = {
         now?: Date;
     }) => Record<string, unknown>;
     buildDerivationDrilldown: (report: Record<string, unknown>, claimId: string) => Record<string, unknown>;
+    /** #171: consumer-ready claim explanation (Surface >=2.10); composes the drilldown internally, fail-soft. */
+    explainClaim: (report: Record<string, unknown>, claimId: string) => import("@kontourai/surface").ClaimExplanation;
     /** Canonical trust-bundle validator from @kontourai/surface. Throws on invalid input; returns TrustBundle on success. */
     validateTrustBundle: (input: unknown) => Record<string, unknown>;
+    /** Canonical InquiryRecord validator from @kontourai/surface. Throws on invalid input; returns InquiryRecord on success. */
+    validateInquiryRecord: (input: unknown) => Record<string, unknown>;
     /** Freeze a derivation checkpoint from a report. */
     checkpointFromReport: (report: Record<string, unknown>) => Record<string, unknown>;
     /** Diff two derivations (prior checkpoint → later report) and emit freshness transition events. */
@@ -203,8 +207,12 @@ export declare function writeTrustBundle(dir: string, slug: string, timestamp: s
 }>;
 export declare function sidecarBase(slug: string): AnyObj;
 export declare function currentWorkflowSessionDir(root: string): string | null;
-export declare function validateEvidenceRef(ref: AnyObj, label: string): AnyObj;
-export declare function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[];
+export declare function validateEvidenceRef(ref: AnyObj, label: string, projectRoot?: string): AnyObj;
+export declare function normalizeEvidenceRefs(raw: unknown, label: string, projectRoot?: string): AnyObj[];
+export declare const NARRATIVE_TRUST_ISOLATION_DIAGNOSTIC = "narrative trust isolation (#619): narrative namespace artifacts cannot be used as workflow evidence";
+export declare function isNarrativeNamespacePath(projectRoot: string, resolvedPath: string): boolean;
+export declare function isNarrativeArtifactContent(fileBytes: Buffer | string): boolean;
+export declare function rejectOperationBoundExpectation(expectationId: string, operation: string): never;
 /** Validate test-evidence command shape without executing it. */
 type TestExecutionProof = {
     kind: "local-process-exit";
@@ -222,7 +230,16 @@ export declare function testExecutionProof(command: string, projectRoot: string,
 export declare function isMeaningfulTestCommand(command: string, projectRoot: string, seenScripts?: Set<string>, packageScriptBody?: boolean): boolean;
 export declare function observedExecutedTestCount(output: string): number;
 export declare function inferExecutedTestCount(command: string, projectRoot: string, output: string, seenScripts?: Set<string>): number;
-export declare function normalizeCheck(raw: AnyObj, allowGateClaimPrefix?: boolean, existingCheckStampById?: ReadonlyMap<string, boolean>): AnyObj;
+type ObservedCommand = {
+    command: string;
+    exit_code: number;
+    output_sha256: string;
+    test_count?: number;
+    execution_proof?: TestExecutionProof;
+};
+export declare const WRITER_OBSERVATION_SOURCE = "canonical-writer-execution";
+export declare function appendWriterObservedCommands(dir: string, observed: ObservedCommand[], timestamp: string): void;
+export declare function normalizeCheck(raw: AnyObj, allowGateClaimPrefix?: boolean, existingCheckStampById?: ReadonlyMap<string, boolean>, projectRoot?: string): AnyObj;
 /**
  * Derive kit identity from a parsed trust.bundle by structurally reading the
  * DECLARED primary claim (kit-typed) rather than hardcoding "builder".
@@ -240,7 +257,7 @@ export declare function kitIdentityFromBundle(raw: AnyObj, bundleFile: string):
     gateId: string;
 };
 export declare function writeState(dir: string, slug: string, status: string, phase: string, timestamp: string, summary: string, next?: string): void;
-export declare function normalizeFinding(raw: AnyObj): AnyObj;
+export declare function normalizeFinding(raw: AnyObj, projectRoot?: string): AnyObj;
 /**
  * Build and write trust.checkpoint.json for a completed run.
  * Skips silently when:
@@ -563,7 +580,7 @@ export declare function runTakeoverPreflight(dir: string, opts?: {
  */
 export declare function publishDelivery(dir: string, repoRoot: string | null): Promise<void>;
 export declare function validateLearningCorrection(record: AnyObj): void;
-export declare function normalizeLearning(raw: AnyObj, timestamp: string): AnyObj;
+export declare function normalizeLearning(raw: AnyObj, timestamp: string, projectRoot?: string): AnyObj;
 /** Shape of a claim from the trust.bundle */
 export interface TrustClaim {
     id: string;
@@ -645,7 +662,6 @@ export declare function gateAdvisoryFix(calibration: GateCalibration, claimId: s
  */
 export declare function buildGateInquiryRecords(bundle: BundleFile, blockSignal: GateBlockSignal, slug: string, expectedCriterionIds: string[], surface: SurfaceModule, now?: Date): AnyObj[];
 export declare const LIVENESS_TERMINAL: Set<string>;
-export { buildClaimExplanation } from "./sidecar-claim-explain.js";
-export type { ClaimEvidenceItem, ClaimExplanation } from "./sidecar-claim-explain.js";
+export type { ClaimEvidenceItem, ClaimExplanation } from "@kontourai/surface";
 export declare function mainFromPublicWorkflow(argv: string[]): Promise<number>;
 export declare function main(argv?: string[], authority?: symbol): Promise<number>;