brainclaw 1.26.2 → 1.28.0

package/dist/core/loops/evidence.js

@@ -0,0 +1,188 @@
+import crypto from 'node:crypto';
+export const GATE_POLICY_VERSION = 'gate-policy-v1';
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, child]) => child !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, child]) => [key, canonicalize(child)]));
+    }
+    return value;
+}
+export function evidenceDigest(value) {
+    return crypto.createHash('sha256').update(JSON.stringify(canonicalize(value))).digest('hex');
+}
+export function artifactEvidenceDigest(artifact) {
+    return evidenceDigest({
+        artifact_id: artifact.artifact_id,
+        phase: artifact.phase,
+        type: artifact.type,
+        ref: artifact.ref,
+        body: artifact.body,
+        produced_by: artifact.produced_by,
+        produced_at: artifact.produced_at,
+        addresses_critique: artifact.addresses_critique,
+        implementation_verify: artifact.implementation_verify,
+        iteration: artifact.iteration ?? 0,
+    });
+}
+/**
+ * Classify both new and historical artifacts without a migration rewrite.
+ * Old sealed envelopes predate the explicit field but are still attested;
+ * old unsealed records remain legacy. The marker is intentionally excluded
+ * from artifactEvidenceDigest so adding it cannot invalidate a v1 seal.
+ */
+export function artifactEvidenceProvenance(artifact) {
+    return artifact.provenance ?? (artifact.evidence ? 'attested' : 'legacy');
+}
+function isAcceptedVerdict(artifact) {
+    return artifact.type === 'verdict' && /^accepted(?:\b|[:\s])/.test((artifact.body ?? '').trim().toLowerCase());
+}
+function attestation(kind, issuer, issued_at, subject_digest, rights) {
+    return { kind, issuer, issued_at, subject_digest, rights };
+}
+/**
+ * Bind evidence at the server-controlled artifact commit boundary. Callers
+ * provide identity context, never an envelope or rights.
+ */
+export function sealArtifactEvidence(thread, artifact, context) {
+    const committedArtifact = {
+        ...artifact,
+        produced_by: context.producer_id,
+        iteration: artifact.iteration ?? thread.iteration_count,
+    };
+    const iteration = committedArtifact.iteration ?? thread.iteration_count;
+    const subject = {
+        loop_id: thread.id,
+        artifact_id: artifact.artifact_id,
+        phase: artifact.phase,
+        iteration,
+        slot_id: context.slot_id,
+        turn_id: context.turn_id,
+        assignment_id: context.assignment_id,
+        claim_id: context.claim_id,
+        run_id: context.run_id,
+        nonce_digest: context.nonce ? evidenceDigest({ launch_nonce: context.nonce }) : undefined,
+        attempt_epoch: context.attempt_epoch,
+        execution_contract_hash: context.execution_contract_hash,
+        command_digest: context.command_digest,
+        workspace_digest: context.workspace_digest,
+    };
+    const subjectDigest = evidenceDigest(subject);
+    const attestations = [];
+    if (context.claim_id) {
+        attestations.push(attestation('claim', 'brainclaw:claim-binding', committedArtifact.produced_at, subjectDigest, ['subject:claim']));
+    }
+    if (context.channel === 'verify_command' && context.producer_kind === 'engine') {
+        attestations.push(attestation('verification', 'brainclaw:verify-command', committedArtifact.produced_at, subjectDigest, ['artifact:write', 'gate:artifact', 'gate:command_green']));
+    }
+    else {
+        const rights = context.channel === 'add_artifact'
+            ? ['artifact:write']
+            : ['artifact:write', 'gate:artifact'];
+        attestations.push(attestation('observation', 'brainclaw:artifact-commit', committedArtifact.produced_at, subjectDigest, rights));
+    }
+    if (isAcceptedVerdict(committedArtifact) &&
+        (context.channel === 'complete_turn' || context.channel === 'reconcile_turn') &&
+        /review/i.test(context.slot_role ?? '')) {
+        attestations.push(attestation('approval', 'brainclaw:review-slot', committedArtifact.produced_at, subjectDigest, ['gate:reviewer_green']));
+    }
+    const unsigned = {
+        version: 1,
+        evidence_id: `evd_${crypto.randomBytes(8).toString('hex')}`,
+        evidence_type: 'artifact_commit',
+        policy_version: GATE_POLICY_VERSION,
+        subject,
+        producer: {
+            kind: context.producer_kind,
+            id: context.producer_id,
+            agent_id: context.agent_id,
+            channel: context.channel,
+        },
+        artifact_digest: artifactEvidenceDigest(committedArtifact),
+        issued_at: committedArtifact.produced_at,
+        observed_at: committedArtifact.produced_at,
+        validity: { not_before: committedArtifact.produced_at },
+        attestations,
+    };
+    const envelope = {
+        ...unsigned,
+        seal: { algorithm: 'sha256', digest: evidenceDigest(unsigned) },
+    };
+    return { ...committedArtifact, provenance: 'attested', evidence: envelope };
+}
+/** Validate every binding before an envelope may influence a gate. */
+export function validateArtifactEvidence(thread, artifact, now = new Date()) {
+    const envelope = artifact.evidence;
+    if (!envelope)
+        return { valid: false, reasons: ['missing_evidence'] };
+    const reasons = [];
+    const { seal, ...unsigned } = envelope;
+    if (seal.algorithm !== 'sha256' || evidenceDigest(unsigned) !== seal.digest)
+        reasons.push('invalid_seal');
+    const { evidence: _ignored, ...unsignedArtifact } = artifact;
+    void _ignored;
+    if (artifactEvidenceDigest(unsignedArtifact) !== envelope.artifact_digest)
+        reasons.push('artifact_digest_mismatch');
+    if (envelope.subject.loop_id !== thread.id)
+        reasons.push('wrong_loop_subject');
+    if (envelope.subject.artifact_id !== artifact.artifact_id)
+        reasons.push('wrong_artifact_subject');
+    if (envelope.subject.phase !== artifact.phase)
+        reasons.push('wrong_phase_subject');
+    if (envelope.subject.iteration !== (artifact.iteration ?? 0))
+        reasons.push('wrong_iteration_subject');
+    if (envelope.issued_at !== artifact.produced_at)
+        reasons.push('issued_at_mismatch');
+    if (envelope.observed_at !== artifact.produced_at)
+        reasons.push('observed_at_mismatch');
+    const issued = Date.parse(envelope.issued_at);
+    const loopCreated = Date.parse(thread.created_at);
+    if (!Number.isFinite(issued))
+        reasons.push('invalid_issued_at');
+    if (Number.isFinite(issued) && Number.isFinite(loopCreated) && issued < loopCreated - 5 * 60_000)
+        reasons.push('stale_before_loop');
+    if (Number.isFinite(issued) && issued > now.getTime() + 5 * 60_000)
+        reasons.push('issued_in_future');
+    const notBefore = Date.parse(envelope.validity.not_before);
+    const notAfter = envelope.validity.not_after ? Date.parse(envelope.validity.not_after) : undefined;
+    if (!Number.isFinite(notBefore) || issued < notBefore)
+        reasons.push('outside_validity_window');
+    if (notAfter !== undefined && (!Number.isFinite(notAfter) || now.getTime() > notAfter))
+        reasons.push('outside_validity_window');
+    if (notAfter !== undefined && Number.isFinite(notBefore) && Number.isFinite(notAfter) && notAfter < notBefore)
+        reasons.push('invalid_validity_window');
+    if (artifact.produced_by !== envelope.producer.id)
+        reasons.push('producer_binding_mismatch');
+    const subjectDigest = evidenceDigest(envelope.subject);
+    for (const item of envelope.attestations) {
+        if (item.subject_digest !== subjectDigest)
+            reasons.push(`attestation_subject_mismatch:${item.kind}`);
+        if (item.issued_at !== envelope.issued_at)
+            reasons.push(`attestation_time_mismatch:${item.kind}`);
+    }
+    return { valid: reasons.length === 0, reasons, evidence_id: envelope.evidence_id };
+}
+export function validateThreadEvidence(thread) {
+    return thread.artifacts.flatMap((artifact) => {
+        if (!artifact.evidence)
+            return [];
+        const result = validateArtifactEvidence(thread, artifact);
+        return result.valid ? [] : [{ artifact_id: artifact.artifact_id, reasons: result.reasons }];
+    });
+}
+/** Feature rollout: new loops are strict unless the writer is explicitly disabled or shadowed. */
+export function evidencePolicyForNewLoop(env = process.env) {
+    const configured = env.BRAINCLAW_EVIDENCE_ENVELOPES?.trim().toLowerCase();
+    if (configured === 'off')
+        return undefined;
+    if (configured === 'shadow')
+        return { version: GATE_POLICY_VERSION, mode: 'shadow' };
+    return { version: GATE_POLICY_VERSION, mode: 'strict' };
+}
+export function evidenceWriterEnabled(env = process.env) {
+    return env.BRAINCLAW_EVIDENCE_ENVELOPES?.trim().toLowerCase() !== 'off';
+}
+//# sourceMappingURL=evidence.js.map

package/dist/core/loops/facade-schema.js

@@ -68,7 +68,11 @@ export const BclawLoopTurnSchema = z.object({
     assignment_id: z.string().optional(),
     /** pln#562 step 4 — claim binding the turn's slot to a dispatched instance. */
     claim_id: z.string().optional(),
+    /** Trusted production driver: claim + AttemptAuthority + message + worker spawn. */
     dispatch: z.boolean().optional(),
+    auto_execute: z.boolean().optional(),
+    model: z.string().min(1).optional(),
+    target_agents: z.array(z.string().min(1)).min(1).optional(),
     expected_version: z.number().int().nonnegative().optional(),
     ...CallerEnvelopeFields,
 });
@@ -76,6 +80,18 @@ export const BclawLoopCompleteTurnSchema = z.object({
     intent: z.literal('complete_turn'),
     loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
     slot_id: z.string().min(1),
+    /**
+     * AttemptAuthority fence. These fields are optional at the transport layer
+     * so pre-v2/legacy turns remain completable, but the verb requires the whole
+     * tuple whenever the slot is backed by AttemptAuthority v2.
+     */
+    assignment_id: z.string().min(1).optional(),
+    turn_id: z.string().min(1).optional(),
+    run_id: z.string().min(1).optional(),
+    nonce: z.string().min(1).optional(),
+    attempt_epoch: z.number().int().nonnegative().optional(),
+    execution_contract_hash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    workspace_digest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     outcome: z.enum(['done', 'failed', 'cancelled']).optional(),
     failure_reason: z.string().optional(),
     artifact: z
@@ -86,11 +102,39 @@ export const BclawLoopCompleteTurnSchema = z.object({
         ref: LoopRefSchema.optional(),
         /** pln#492 synthesis audit trail. Required when type === 'plan_draft'. */
         addresses_critique: z.array(z.string().min(1)).optional(),
+        implementation_verify: z
+            .object({
+            command: z.array(z.string().min(1)).min(1),
+            timeout_ms: z.number().int().positive().optional(),
+        })
+            .optional(),
+    })
+        .superRefine((artifact, ctx) => {
+        if (artifact.type === 'plan_draft' && !artifact.implementation_verify) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "plan_draft requires implementation_verify for deterministic downstream verification",
+                path: ['implementation_verify'],
+            });
+        }
     })
         .optional(),
     expected_version: z.number().int().nonnegative().optional(),
     ...CallerEnvelopeFields,
 });
+export const BclawLoopTakeoverSchema = z.object({
+    intent: z.literal('takeover'),
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    slot_id: z.string().min(1),
+    turn_id: z.string().min(1),
+    expected_epoch: z.number().int().nonnegative(),
+    cause: z.string().min(1),
+    liveness_evidence: z.string().min(1),
+    external_effect_policy: z.enum(['none', 'idempotent', 'externally_fenced']),
+    next_workspace_path: z.string().min(1),
+    takeover_mode: z.enum(['takeover', 'retry']).optional(),
+    ...CallerEnvelopeFields,
+});
 export const BclawLoopAdvanceSchema = z.object({
     intent: z.literal('advance'),
     loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
@@ -103,14 +147,29 @@ export const BclawLoopAdvanceSchema = z.object({
 export const BclawLoopAddArtifactSchema = z.object({
     intent: z.literal('add_artifact'),
     loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
-    artifact: z.object({
+    artifact: z
+        .object({
         phase: z.string().min(1),
         type: z.string().min(1),
         body: z.string().optional(),
-        produced_by: z.string().optional(),
         ref: LoopRefSchema.optional(),
         /** pln#492 synthesis audit trail. Required when type === 'plan_draft'. */
         addresses_critique: z.array(z.string().min(1)).optional(),
+        implementation_verify: z
+            .object({
+            command: z.array(z.string().min(1)).min(1),
+            timeout_ms: z.number().int().positive().optional(),
+        })
+            .optional(),
+    })
+        .superRefine((artifact, ctx) => {
+        if (artifact.type === 'plan_draft' && !artifact.implementation_verify) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "plan_draft requires implementation_verify for deterministic downstream verification",
+                path: ['implementation_verify'],
+            });
+        }
     }),
     expected_version: z.number().int().nonnegative().optional(),
     ...CallerEnvelopeFields,
@@ -145,29 +204,32 @@ export const BclawLoopCloseSchema = z.object({
 export const BclawLoopVerifySchema = z.object({
     intent: z.literal('verify'),
     loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    /** Required when an implementation loop has more than one bound lane. */
+    slot_id: z.string().regex(/^lsl_[0-9a-z]+$/).optional(),
     // No expected_version: runVerify is idempotent by (loop, iteration) via its own
     // two-lock re-check, not optimistic-concurrency CAS (review F3).
     ...CallerEnvelopeFields,
 });
 /**
  * pln#632 — `bclaw_loop(intent='bind')`: the ENGINE action for an implementation loop's
- * `bind` phase. Dispatches the loop's linked sequence (by id, no active-sequence hijack)
- * and advances `bind → execute`. Idempotent (a loop past `bind` → noop). `dry_run`
- * previews what would dispatch without spawning or advancing. Implementation loops only —
- * review/ideation loops dispatch via bclaw_coordinate.
+ * `bind` phase. Validates the loop's linked sequence and advances
+ * `bind → execute`; it never dispatches a worker. Idempotent (a loop past
+ * `bind` → noop). `dry_run` validates without advancing. Historical launch
+ * options remain accepted but are ignored during migration; worker launch is
+ * exclusively `turn(dispatch=true)` through AttemptAuthority.
  */
 export const BclawLoopBindSchema = z.object({
     intent: z.literal('bind'),
     loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
-    /** Analyze + report what would dispatch; no spawn, no advance. */
+    /** Validate the linked sequence; no advance. Bind never spawns. */
     dry_run: z.boolean().optional(),
-    /** Restrict the bind dispatch to specific lanes. */
+    /** @deprecated Retained for compatibility and ignored. */
     lanes: z.array(z.string().min(1)).optional(),
-    /** Deliver briefs without spawning (→ manual launch commands). */
+    /** @deprecated Retained for compatibility and ignored. */
     auto_execute: z.boolean().optional(),
-    /** Model override for the dispatched agents. */
+    /** @deprecated Retained for compatibility and ignored. */
     model: z.string().min(1).optional(),
-    /** Cap assignments made in this bind. */
+    /** @deprecated Retained for compatibility and ignored. */
     max_assignments: z.number().int().positive().optional(),
     // No expected_version: bind is idempotent by loop phase (past `bind` → noop), not CAS.
     ...CallerEnvelopeFields,
@@ -236,6 +298,7 @@ export const BclawLoopRequestSchema = z.discriminatedUnion('intent', [
     BclawLoopListSchema,
     BclawLoopTurnSchema,
     BclawLoopCompleteTurnSchema,
+    BclawLoopTakeoverSchema,
     BclawLoopAdvanceSchema,
     BclawLoopAddArtifactSchema,
     BclawLoopPauseSchema,
@@ -252,6 +315,7 @@ export const BCLAW_LOOP_INTENTS = [
     'list',
     'turn',
     'complete_turn',
+    'takeover',
     'advance',
     'add_artifact',
     'pause',