@kontourai/flow-agents 1.4.0 → 2.0.0

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

@@ -9,24 +9,316 @@ export declare function writeJson(file: string, payload: AnyObj): void;
 export declare function loadJson(file: string, fallback?: AnyObj): AnyObj;
 export declare function appendJsonl(file: string, payload: AnyObj): void;
 /**
- * Validate a Hachure trust.bundle against the canonical trust-bundle schema.
- * Returns `{ valid, errors, available }`. When the optional `hachure` dependency
- * is not installed, validation is unavailable and this returns
- * `{ valid: true, errors: [], available: false }` (fail-open) so callers can
- * choose to treat unvalidated bundles as acceptable or gate on `available`.
- * This is the same validator the sidecar writer uses for trust-backed evidence.
- */
-export declare function validateTrustBundle(bundle: unknown): {
+ * Validate a Hachure trust.bundle using @kontourai/surface's canonical validator
+ * (surface is the authoritative owner of trust-bundle schema validation per ADR 0010 / ADR 0015).
+ * Returns `{ valid, errors, available }`. When @kontourai/surface is unavailable,
+ * `available` is false and `valid` is true (fail-open) so callers can choose to treat
+ * unvalidated bundles as acceptable or gate on `available`. Surface is REQUIRED for
+ * bundle writes per ADR 0010 Phase 4c — `assertBundleWritten` enforces this on the
+ * write path. Surface's validator is equivalent-or-stronger than the prior hachure
+ * JSON-Schema validator: it validates the same structural constraints plus cross-reference
+ * integrity (evidence/event → claim references) that the JSON schema did not enforce.
+ */
+export declare function validateTrustBundle(bundle: unknown): Promise<{
+    valid: boolean;
+    errors: string[];
+    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.
+ */
+export declare function validateInquiryRecord(record: unknown): {
     valid: boolean;
     errors: string[];
     available: boolean;
 };
+type SurfaceInquiry = {
+    id: string;
+    question: string;
+    askedBy: string;
+    askedAt: string;
+    target?: {
+        subjectType: string;
+        subjectId: string;
+        fieldOrBehavior: string;
+        qualifiers?: Record<string, string>;
+    };
+    metadata?: Record<string, unknown>;
+};
+type SurfaceInquiryRecord = {
+    id: string;
+    inquiry: SurfaceInquiry;
+    outcome: "matched" | "derived" | "unsupported";
+    resolutionPath: {
+        claimIds: string[];
+        ruleId?: string;
+        ruleVersion?: string;
+        identityLinkIds?: string[];
+        transitiveRuleIds?: string[];
+    };
+    answer?: {
+        value: unknown;
+        status: string;
+    };
+    inputSnapshot: Array<{
+        claimId: string;
+        status: string;
+    }>;
+    statusFunctionVersion: string;
+    resolvedAt: string;
+};
+type SurfaceModule = {
+    deriveClaimStatus: (args: {
+        claim: Record<string, unknown>;
+        evidence: Record<string, unknown>[];
+        events: Record<string, unknown>[];
+        policies: Record<string, unknown>[];
+        now?: Date;
+    }) => {
+        status: string;
+        policyId: string | undefined;
+    };
+    generateClaimId: (subjectId: string, surface: string, fieldOrBehavior: string) => string;
+    statusFunctionVersion: string;
+    resolveInquiry: (bundle: Record<string, unknown>, inquiry: SurfaceInquiry, options?: {
+        now?: Date;
+    }) => SurfaceInquiryRecord;
+    buildTrustReport: (bundle: Record<string, unknown>, options?: {
+        now?: Date;
+    }) => Record<string, unknown>;
+    buildDerivationDrilldown: (report: Record<string, unknown>, claimId: string) => Record<string, unknown>;
+    /** Canonical trust-bundle validator from @kontourai/surface. Throws on invalid input; returns TrustBundle on success. */
+    validateTrustBundle: (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. */
+    diffFreshness: (prior: Record<string, unknown>, next: Record<string, unknown>) => Array<Record<string, unknown>>;
+    /** Wrap a TrustBundle as an in-toto Statement v1. */
+    toInTotoStatement: (bundle: Record<string, unknown>, options: {
+        subjects: Array<{
+            name: string;
+            digest: Record<string, string>;
+        }>;
+    }) => {
+        _type: "https://in-toto.io/Statement/v1";
+        subject: Array<{
+            name: string;
+            digest: Record<string, string>;
+        }>;
+        predicateType: "https://hachure.org/v1/bundle";
+        predicate: Record<string, unknown>;
+    };
+    /** Sign an in-toto Statement with Sigstore keyless signing. Returns null when no OIDC identity is available (fail-open). */
+    signStatementWithSigstore: (statement: {
+        _type: "https://in-toto.io/Statement/v1";
+        subject: Array<{
+            name: string;
+            digest: Record<string, string>;
+        }>;
+        predicateType: "https://hachure.org/v1/bundle";
+        predicate: Record<string, unknown>;
+    }) => Promise<{
+        envelope: {
+            payloadType: "application/vnd.in-toto+json";
+            payload: string;
+            signatures: Array<{
+                keyid: string;
+                sig: string;
+            }>;
+        };
+        sigstoreBundle: unknown;
+        assuranceLevel: "signed";
+    } | null>;
+};
+/**
+ * Build a Hachure trust.bundle from raw check/criterion/critique inputs.
+ * trust.bundle is the PRIMARY artifact (ADR 0010 Phase 4a producer inversion).
+ * Callers pass raw inputs directly — not bespoke-sidecar-shaped objects.
+ * Derives claim statuses using @kontourai/surface's canonical versioned function.
+ * Returns null when Surface is unavailable (caller skips the bundle write).
+ * @param slug       Task slug (used as subjectId prefix)
+ * @param timestamp  ISO-8601 timestamp for createdAt / updatedAt / observedAt
+ * @param checks     Normalized check objects (from record-evidence --check-json / --surface-trust-json)
+ * @param criteria   Acceptance criteria objects (from acceptance.json .criteria array)
+ * @param critiques  Critique objects (from critique.json .critiques array)
+ * @param commandLog Optional parsed command-log.jsonl entries (capture-authoritative fold)
+ */
+export declare function buildTrustBundle(slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], commandLog?: AnyObj[], flowAgentsDir?: string): Promise<AnyObj | null>;
+/**
+ * Fail-open wrapper: builds (via Surface), validates, and writes a trust.bundle.
+ * Accepts raw check/criterion/critique inputs directly (ADR 0010 Phase 4a).
+ * trust.bundle is written as the PRIMARY artifact; bespoke sidecars are the
+ * caller's responsibility to emit as back-compat projections AFTER this call.
+ * ANY error is caught and logged to stderr — this function NEVER throws and
+ * NEVER affects the exit code of its caller.
+ * Returns { written: false } if Surface is unavailable (fail-open; does NOT
+ * fall back to hand-rolled status derivation).
+ * @param checks     Normalized check objects (same as buildTrustBundle)
+ * @param criteria   Acceptance criteria objects (same as buildTrustBundle)
+ * @param critiques  Critique objects (same as buildTrustBundle)
+ */
+export declare function writeTrustBundle(dir: string, slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[]): Promise<{
+    written: boolean;
+    errors: string[];
+}>;
 export declare function sidecarBase(slug: string): AnyObj;
 export declare function validateEvidenceRef(ref: AnyObj, label: string): AnyObj;
 export declare function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[];
 export declare function normalizeCheck(raw: AnyObj): AnyObj;
 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;
+/**
+ * Build and write trust.checkpoint.json for a completed run.
+ * Skips silently when:
+ *   - trust.bundle is absent (no evidence recorded yet)
+ *   - Surface is unavailable (checkpointFromReport not found)
+ * The caller wraps this in .catch() so it never breaks the parent command.
+ *
+ * Increment B1 — checkpoint signing at the release boundary:
+ * After the checkpoint is written, attempts Sigstore keyless signing (OIDC).
+ *   - CI/OIDC available:   writes trust.checkpoint.sig.json (cosign-verifiable DSSE envelope)
+ *                          and writes attestation:{status:"signed",...} to trust.checkpoint.attestation.json.
+ *   - Local (no OIDC):     writes trust.checkpoint.intoto.json (unsigned in-toto statement)
+ *                          and writes attestation:{status:"unsigned",...} to trust.checkpoint.attestation.json.
+ * Signing is ALWAYS fail-open — a signing failure never breaks the seal.
+ */
+export declare function sealTrustCheckpoint(dir: string, slug: string, sealedAt: string, status: string, phase: string): Promise<void>;
+/**
+ * Publish the session's trust artifacts to the committed delivery/ path.
+ *
+ * Copies trust.bundle, trust.checkpoint.json, and (if present)
+ * trust.checkpoint.intoto.json / trust.checkpoint.sig.json from the
+ * session artifact dir to <repoRoot>/delivery/.
+ *
+ * Fail-soft: if trust.bundle is absent, returns without throwing.
+ * Idempotent: overwrites on re-delivery.
+ */
+export declare function publishDelivery(dir: string, repoRoot: string): Promise<void>;
 export declare function validateLearningCorrection(record: AnyObj): void;
 export declare function normalizeLearning(raw: AnyObj, timestamp: string): AnyObj;
+/** Shape of a claim from the trust.bundle */
+export interface TrustClaim {
+    id: string;
+    subjectType: string;
+    subjectId: string;
+    surface: string;
+    claimType: string;
+    fieldOrBehavior: string;
+    value: string;
+    createdAt: string;
+    updatedAt: string;
+    status: "verified" | "disputed" | "assumed" | "proposed" | "rejected" | "stale" | "unknown";
+}
+/** Shape of the trust.bundle file */
+export interface BundleFile {
+    schemaVersion: number;
+    source: string;
+    claims: TrustClaim[];
+    evidence: AnyObj[];
+    events: AnyObj[];
+    policies: AnyObj[];
+}
+/** The gate block signal read from .flow-agents/.goal-fit-block-streak.json */
+export interface GateBlockSignal {
+    /** True when the streak file exists AND count >= 1 */
+    blocked: boolean;
+    /** The hash from the streak file (for rationale citation) */
+    hash: string | null;
+    /** The consecutive block count */
+    count: number;
+}
+/**
+ * The gate-review calibration verdict, stored in InquiryRecord.answer.value.
+ * This is gate-review's value-add over the canonical InquiryRecord outcome.
+ */
+export type GateCalibration = "correct" | "false_block" | "missed_block";
+/**
+ * Read the gate block signal from .flow-agents/.goal-fit-block-streak.json
+ * (written by scripts/hooks/stop-goal-fit.js when block mode fires).
+ * The file sits at <artifact-root>/.goal-fit-block-streak.json — one level
+ * above the session artifact dir. Fail-open: returns { blocked: false } when
+ * the file is absent or unreadable.
+ *
+ * @param artifactRoot  The .flow-agents root dir (parent of session slug dir).
+ */
+export declare function readGateBlockSignal(artifactRoot: string): GateBlockSignal;
+/**
+ * Derive the gate-review calibration from a resolved InquiryRecord and the
+ * block signal.  Pure function — no I/O.
+ *
+ * Mapping (mirrors SKILL.md Bundle-Claim to Classification table):
+ *   outcome="matched", status="disputed"|"rejected", blocked=true  → correct
+ *   outcome="matched", status="verified"|"assumed",  blocked=true  → false_block
+ *   outcome="matched", status="assumed",             blocked=true  → false_block
+ *   outcome="matched", status="stale"|"unknown",     blocked=false → missed_block
+ *   outcome="matched", status="proposed",            any          → missed_block
+ *   outcome="unsupported" (absent claim),            any          → missed_block
+ *   outcome="derived",   satisfied=true,             any          → correct/false_block by blocked flag
+ *   fallthrough                                                    → missed_block
+ */
+export declare function deriveGateCalibration(outcome: "matched" | "derived" | "unsupported", answerStatus: string | undefined, blocked: boolean): GateCalibration;
+/**
+ * Compose the advisory proposed-fix string for a gate-review finding.
+ * Pure function — no I/O.
+ */
+export declare function gateAdvisoryFix(calibration: GateCalibration, claimId: string, answerStatus: string | undefined): string;
+/**
+ * Build an array of canonical InquiryRecords for all gate-fire and missed-block
+ * candidates in the bundle, using Surface's resolveInquiry.  Returns null when
+ * Surface is unavailable (caller skips the output file — no fork fallback).
+ *
+ * @param bundle              Parsed trust.bundle (BundleFile shape)
+ * @param blockSignal         Result of readGateBlockSignal()
+ * @param slug                Task slug (used in inquiry ids and session_slug)
+ * @param expectedCriterionIds Optional list of expected criterion IDs to check
+ *                            for absent claims (missed_block detection).
+ * @param surface             Loaded Surface module (must have resolveInquiry)
+ * @param now                 Optional timestamp override for deterministic tests
+ */
+export declare function buildGateInquiryRecords(bundle: BundleFile, blockSignal: GateBlockSignal, slug: string, expectedCriterionIds: string[], surface: SurfaceModule, now?: Date): AnyObj[];
+export interface ClaimEvidenceItem {
+    evidenceType: string;
+    label: string;
+    execution: {
+        runner: string;
+        label: string;
+        isError: boolean;
+        exitCode: number | null;
+    } | null;
+    passing: boolean;
+    summary: string;
+}
+export interface ClaimExplanation {
+    found: boolean;
+    status: string;
+    value: string;
+    claimType: string;
+    evidence: ClaimEvidenceItem[];
+    policy: {
+        id: string;
+        requiredEvidence: string[];
+        requiredMethods?: string[];
+        acceptanceCriteria: string[];
+        reviewAuthority: string;
+    } | null;
+    why: {
+        directInputs: AnyObj[];
+        leafClaims: AnyObj[];
+        diagnostics: AnyObj[];
+        transparencyGaps: AnyObj[];
+        changeRecords: AnyObj[];
+    };
+}
+/**
+ * Build a structured explanation for a specific claim.
+ * PURE: report + bundle + id in, structured explanation out.
+ * No fs, no CLI, no .flow-agents paths. Promotable to Surface #171.
+ *
+ * @param report   TrustReport from buildTrustReport(bundle) — required for derived status
+ * @param bundle   Raw parsed trust.bundle (BundleFile shape)
+ * @param claimId  The claim id to explain
+ */
+export declare function buildClaimExplanation(report: Record<string, unknown>, bundle: Record<string, unknown>, claimId: string): ClaimExplanation;
 export {};