@inflexa-ai/harness 0.36.4 → 0.38.0

package/README.md

@@ -35,7 +35,6 @@ import {
     createConfiguredAiSdkProvider,  // ChatProvider — any OpenAI-compatible endpoint
     createEmbeddingProvider,
     createLocalRunAuthorizer,       // RunAuthorizer    seam (local default)
-    createNoopBillingResolver,      // ResolveBilling   seam
     createNoopRunCharge,            // RunCharge        seam
     createNoopUsageRecorder,        // UsageRecorder    seam
     createNoopArtifactRegistry,     // ArtifactRegistry seam
@@ -49,7 +48,7 @@ import {
 } from "@inflexa-ai/harness";
 ```
 
-`assembleCoreRuntime` is the single composition point: it registers the durable workflows and builds the conversation agent over them. The harness declares **five capability seams** an embedder wires — `RunAuthorizer`, `ResolveBilling`, `ArtifactRegistry`, `RunCharge`, `UsageRecorder` — plus the **shared `RunLauncher`** (one host-neutral realization, `createDbosRunLauncher`). Local, dependency-free realizations of all five ship from the barrel; an embedder constructs them (or its own) and passes them in. The harness only ever sees the interface.
+`assembleCoreRuntime` is the single composition point: it registers the durable workflows and builds the conversation agent over them. The harness declares **four capability seams** an embedder wires — `RunAuthorizer`, `ArtifactRegistry`, `RunCharge`, `UsageRecorder` — plus the **shared `RunLauncher`** (one host-neutral realization, `createDbosRunLauncher`). Local, dependency-free realizations of all four ship from the barrel; an embedder constructs them (or its own) and passes them in. The harness only ever sees the interface. Two optional hooks go into the component that uses their values: `resolveRequestHeaders` into each provider, and `resolveSandboxLabels` into the sandbox client config.
 
 ## Logging
 

package/dist/auth/local-run-authorizer.js

@@ -7,9 +7,10 @@
  * forwarded untouched — local code never
  * inspects it (no `getAuth`).
  */
+import { okAsync } from "neverthrow";
 export function createLocalRunAuthorizer() {
     return {
-        async authorize({ auth, scope, provenance, frame }) {
+        authorize({ auth, scope, provenance, frame }) {
             const runSession = {
                 identity: { user: "local" },
                 scope,
@@ -17,9 +18,9 @@ export function createLocalRunAuthorizer() {
                 runFrame: frame,
                 auth,
             };
-            return { runSession, ownsMandate: false }; // oss-core-managed-ok
+            return okAsync({ runSession, ownsMandate: false }); // oss-core-managed-ok
         },
-        async revoke() { },
-        async revokeByJti() { },
+        revoke: () => okAsync(undefined),
+        revokeByJti: () => okAsync(undefined),
     };
 }

package/dist/auth/types.d.ts

@@ -16,8 +16,9 @@
  *   - `RunSession` — durable, JSON-serializable. Carries a `RunFrame`; minted
  *     only at the run-authorization seam.
  *
- * Neither bundle carries resolved billing headers — billing is resolved
- * lazily at the LLM call site (see `harness/billing/resolver.ts`).
+ * Neither bundle carries request headers — a provider gets them at the call
+ * site from the optional request headers hook of the host (see
+ * `providers/request-headers.ts`).
  */
 /** Who the request is. Always complete. */
 export interface Identity {
@@ -89,7 +90,7 @@ export interface AuthContext {
  * consumer is the provider, which reads every field, so the conduit type is
  * "all fields, generalized to what's read" — `credential` widened to the
  * opaque `Credential` (nothing in the harness branches on the concrete shape),
- * `runFrame` optional (only the billing assembler reads it).
+ * `runFrame` optional (only a host hook reads it).
  *
  * Both bundles satisfy this: a `RequestSession` (no RunFrame) and a
  * `RunSession` (with RunFrame) are each structurally assignable, so the
@@ -130,16 +131,33 @@ export interface RunSession {
     readonly auth: AuthContext;
 }
 /**
- * The minimal session view the billing-header assembler reads. Both bundles
- * satisfy it; `runFrame` is present only on a `RunSession`, so a
- * `RequestSession` emits no run/step tags.
+ * The session of a sandbox spawn. A sandbox takes its analysis id, its run id,
+ * and its step id from this session.
  */
-export interface BillingSessionView {
+export interface SpawnSession extends RunSession {
+    readonly runFrame: RunFrame & {
+        readonly stepId: string;
+    };
+}
+/**
+ * The minimal session view that a host hook reads. Both bundles satisfy it;
+ * `runFrame` is present only on a `RunSession`, so a hook that gets a
+ * `RequestSession` sees no run or step.
+ */
+export interface HookSessionView {
     readonly identity: Identity;
     readonly scope: Scope;
     readonly provenance: Provenance;
     readonly runFrame?: RunFrame;
 }
+/**
+ * The session that the request headers hook gets: the hook view plus the
+ * opaque `auth`, which a host realization downcasts to reach its credential.
+ * `AgentSession` structurally satisfies it.
+ */
+export interface ResolvableSession extends HookSessionView {
+    readonly auth: AuthContext;
+}
 /**
  * Derive a child session for a sub-agent call — provenance only. Sets the
  * child `agentId` and appends it to `callPath`, leaving identity, scope, and
@@ -151,7 +169,8 @@ export declare function forSubAgent<S extends {
 /**
  * Derive a child `RunSession` for a sandbox step — pure value derivation.
  * Sets `runFrame.stepId`; identity, scope, auth, and provenance are
- * unchanged. Used by parents when computing child workflow input.
+ * unchanged. Used by parents when computing child workflow input, and by a
+ * spawn path that names the step of its sandbox.
  */
-export declare function forStep(parent: RunSession, stepId: string): RunSession;
+export declare function forStep(parent: RunSession, stepId: string): SpawnSession;
 export {};

package/dist/auth/types.js

@@ -16,8 +16,9 @@
  *   - `RunSession` — durable, JSON-serializable. Carries a `RunFrame`; minted
  *     only at the run-authorization seam.
  *
- * Neither bundle carries resolved billing headers — billing is resolved
- * lazily at the LLM call site (see `harness/billing/resolver.ts`).
+ * Neither bundle carries request headers — a provider gets them at the call
+ * site from the optional request headers hook of the host (see
+ * `providers/request-headers.ts`).
  */
 /** Derive the `{ resourceType, resourceId }` a scope resolves through: `{ "analysis", analysisId }`. */
 export function scopeResource(scope) {
@@ -44,7 +45,8 @@ export function forSubAgent(session, agentId) {
 /**
  * Derive a child `RunSession` for a sandbox step — pure value derivation.
  * Sets `runFrame.stepId`; identity, scope, auth, and provenance are
- * unchanged. Used by parents when computing child workflow input.
+ * unchanged. Used by parents when computing child workflow input, and by a
+ * spawn path that names the step of its sandbox.
  */
 export function forStep(parent, stepId) {
     return {

package/dist/billing/noop-run-charge.js

@@ -1,10 +1,11 @@
+import { okAsync } from "neverthrow";
 /**
  * Local/OSS run-charge seam: open and close are both no-ops. No external
  * billing ledger in the cloud-free build.
  */
 export function createNoopRunCharge() {
     return {
-        open: async () => { },
-        close: async () => { },
+        open: () => okAsync(undefined),
+        close: () => okAsync(undefined),
     };
 }

package/dist/billing/noop-usage-recorder.js

@@ -1,3 +1,4 @@
+import { okAsync } from "neverthrow";
 /**
  * Local/OSS usage recorder: drops every record. No ledger, no I/O — the
  * default an embedder that wires nothing gets. Runs behave exactly as they did
@@ -5,6 +6,6 @@
  */
 export function createNoopUsageRecorder() {
     return {
-        record: () => { },
+        record: () => okAsync(undefined),
     };
 }

package/dist/billing/run-charge.d.ts

@@ -2,23 +2,36 @@
  * `RunCharge` — the run-level billing-bracket seam.
  *
  * `executeAnalysis` opens a running charge at init and closes it on the
- * terminal path with one of four reasons. A managed embedder wires an
+ * terminal path with the outcome of the run. A managed embedder wires an
  * external running-charge bracket; OSS wires a no-op. The harness only ever sees this
  * interface — the body brackets the run, the embedder owns the ledger.
+ *
+ * `open` is a gate: an `err` ends the run before a step starts, or suspends it
+ * when the host asks. `close` is a notice: an `err` is logged, and the terminal
+ * status of the run does not change (see `lib/hooks.ts`).
  */
+import type { ResultAsync } from "neverthrow";
 import type { AgentSession } from "../auth/types.js";
+import type { GateFailure, NoticeFailure } from "../lib/hooks.js";
+/** A suspension carries the reason of the host, which the harness does not read. */
+export type RunChargeOutcome = {
+    readonly kind: "ok" | "error" | "canceled";
+} | {
+    readonly kind: "suspended";
+    readonly reason: string;
+};
 export interface RunCharge {
     /** Open the run's running charge at init. */
     open(args: {
         analysisId: string;
         runId: string;
         session: AgentSession;
-    }): Promise<void>;
-    /** Close the run's running charge with one of four terminal reasons. */
+    }): ResultAsync<void, GateFailure>;
+    /** Close the run's running charge with the outcome of the run. */
     close(args: {
         analysisId: string;
         runId: string;
-        reason: "ok" | "error" | "canceled" | "budget_exceeded";
+        outcome: RunChargeOutcome;
         session: AgentSession;
-    }): Promise<void>;
+    }): ResultAsync<void, NoticeFailure>;
 }

package/dist/billing/run-charge.js

@@ -2,8 +2,12 @@
  * `RunCharge` — the run-level billing-bracket seam.
  *
  * `executeAnalysis` opens a running charge at init and closes it on the
- * terminal path with one of four reasons. A managed embedder wires an
+ * terminal path with the outcome of the run. A managed embedder wires an
  * external running-charge bracket; OSS wires a no-op. The harness only ever sees this
  * interface — the body brackets the run, the embedder owns the ledger.
+ *
+ * `open` is a gate: an `err` ends the run before a step starts, or suspends it
+ * when the host asks. `close` is a notice: an `err` is logged, and the terminal
+ * status of the run does not change (see `lib/hooks.ts`).
  */
 export {};

package/dist/billing/usage-recorder.d.ts

@@ -1,9 +1,8 @@
 /**
  * `UsageRecorder` — the per-call LLM usage-accounting seam.
  *
- * Sibling of `ResolveBilling` and `RunCharge`, and complementary to both:
- * `ResolveBilling` stamps attribution onto a wire call, `RunCharge` brackets a
- * run for managed billing, and `UsageRecorder` streams the fine-grained token
+ * Sibling of `RunCharge`, and complementary to it: `RunCharge` brackets a run
+ * for managed billing, and `UsageRecorder` streams the fine-grained token
  * telemetry every completed LLM call produces. The harness names no storage or
  * display technology — it emits records; the embedder decides where they land.
  *
@@ -12,7 +11,9 @@
  * composition root and reaches every `runAgent` invocation through the deps
  * bags. OSS default: `createNoopUsageRecorder` (`./noop-usage-recorder.ts`).
  */
+import type { ResultAsync } from "neverthrow";
 import type { Scope } from "../auth/types.js";
+import type { NoticeFailure } from "../lib/hooks.js";
 import type { ChatUsage } from "../providers/types.js";
 /** One completed LLM call's token usage, with the attribution held at the call site. */
 export interface LlmUsageRecord {
@@ -52,12 +53,13 @@ export interface LlmUsageRecord {
 /**
  * Records one `LlmUsageRecord` per completed LLM call.
  *
- * Fire-and-forget: the loop neither awaits `record` nor guards it, so a
- * realization MUST NOT throw and MUST NOT block — buffer and flush
- * internally, and own your error handling (diagnostics belong on the injected
- * `Logger`). A recorder that violates the contract fails or stalls the run it
- * was only meant to observe.
+ * `record` is a notice (see `lib/hooks.ts`). It gives a failure as an `err`,
+ * never as a throw. The loop does not wait for the result and puts no `try`
+ * around the call. When the result arrives, the loop logs the reason of an
+ * `err`, and the run continues with no change. A recorder that blocks does not
+ * make a run slower, but a realization that throws before it returns a
+ * `ResultAsync` still fails the run it was only meant to observe.
  */
 export interface UsageRecorder {
-    record(record: LlmUsageRecord): void;
+    record(record: LlmUsageRecord): ResultAsync<void, NoticeFailure>;
 }

package/dist/billing/usage-recorder.js

@@ -1,9 +1,8 @@
 /**
  * `UsageRecorder` — the per-call LLM usage-accounting seam.
  *
- * Sibling of `ResolveBilling` and `RunCharge`, and complementary to both:
- * `ResolveBilling` stamps attribution onto a wire call, `RunCharge` brackets a
- * run for managed billing, and `UsageRecorder` streams the fine-grained token
+ * Sibling of `RunCharge`, and complementary to it: `RunCharge` brackets a run
+ * for managed billing, and `UsageRecorder` streams the fine-grained token
  * telemetry every completed LLM call produces. The harness names no storage or
  * display technology — it emits records; the embedder decides where they land.
  *

package/dist/contracts/chat-events.d.ts

@@ -124,7 +124,10 @@ export interface ChatErrorEvent {
     type: "error";
     /** Human-readable, scrubbed error message. */
     message: string;
-    /** Machine-readable failure code, e.g. `"budget_exceeded"`. */
+    /**
+     * Machine-readable failure code. For a turn that a `suspend` error failed, it
+     * is the suspend reason of the host, carried unread (`suspensionOfFailure`).
+     */
     reason?: string;
     source: EventSource;
 }

package/dist/contracts/chat-parts.d.ts

@@ -339,7 +339,7 @@ export interface RunFailedPart {
     runId: string;
     /** Scrubbed error message (no internal details). */
     error: string;
-    /** Machine-readable failure reason (e.g., "budget_exceeded"). */
+    /** The suspend reason of the host, carried unread; present only when the run suspended. */
     reason?: string;
 }
 /**

package/dist/contracts/message.d.ts

@@ -74,4 +74,19 @@ export interface CortexMessage {
      * zero is a figure, thus it stays a value and it never reads as an absence.
      */
     durationMs?: number;
+    /**
+     * Who sent this message — the identity the host named at the append site.
+     * Carried on a `user` message only: `role` already names the sender of a
+     * reply, and the harness holds no per-turn model name at the store boundary.
+     * Absent means that nothing recorded a sender.
+     */
+    author?: string;
+    /**
+     * When the store wrote this message: the START time of the append
+     * transaction, thus every message of one append carries the same value and
+     * no order holds between two appends. An ISO 8601 string rather than a
+     * `Date`, because the wire shape is JSON. Absent means that no stored row
+     * backs the message — a live surface builds one before anything is written.
+     */
+    createdAt?: string;
 }

package/dist/contracts/schemas/chat-parts.d.ts

@@ -151,10 +151,10 @@ export declare const RunStartedPartSchema: z.ZodObject<{
     stepCount: z.ZodNumber;
 }, z.core.$strip>;
 export declare const StepStatusSchema: z.ZodEnum<{
+    failed: "failed";
     pending: "pending";
     running: "running";
     completed: "completed";
-    failed: "failed";
     skipped: "skipped";
     queued: "queued";
 }>;
@@ -163,10 +163,10 @@ export declare const DagStepStateSchema: z.ZodObject<{
     name: z.ZodString;
     agent: z.ZodString;
     status: z.ZodEnum<{
+        failed: "failed";
         pending: "pending";
         running: "running";
         completed: "completed";
-        failed: "failed";
         skipped: "skipped";
         queued: "queued";
     }>;
@@ -186,10 +186,10 @@ export declare const DagStatePartSchema: z.ZodObject<{
         name: z.ZodString;
         agent: z.ZodString;
         status: z.ZodEnum<{
+            failed: "failed";
             pending: "pending";
             running: "running";
             completed: "completed";
-            failed: "failed";
             skipped: "skipped";
             queued: "queued";
         }>;
@@ -570,10 +570,10 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         name: z.ZodString;
         agent: z.ZodString;
         status: z.ZodEnum<{
+            failed: "failed";
             pending: "pending";
             running: "running";
             completed: "completed";
-            failed: "failed";
             skipped: "skipped";
             queued: "queued";
         }>;

package/dist/execution/artifact-registration.d.ts

@@ -9,8 +9,10 @@
  * (an external provenance ledger, or a filesystem index) is a composition-root
  * decision — this module never names one.
  */
+import { type Result } from "neverthrow";
 import type { Pool, PoolClient } from "pg";
 import type { AgentSession } from "../auth/types.js";
+import { type GateRefusal } from "../lib/hooks.js";
 import type { Logger } from "../lib/logger.js";
 import type { ArtifactRegistry, ArtifactRegistrationInput } from "./artifact-registry.js";
 export type { ArtifactRegistrationInput };
@@ -33,5 +35,8 @@ export interface ArtifactRegistrationResult {
  * Builds the `cortex_artifacts` rows from the manifest, upserts them, then
  * delegates external provenance registration to the injected `ArtifactRegistry`
  * and applies any returned external ids back onto the local rows.
+ *
+ * A refusal of `register` writes no external id: the upserted rows keep
+ * `artifact_id = NULL`.
  */
-export declare function registerStepArtifacts(db: Pool | PoolClient, registry: ArtifactRegistry, input: ArtifactRegistrationInput, session: AgentSession, logger?: Logger): Promise<ArtifactRegistrationResult>;
+export declare function registerStepArtifacts(db: Pool | PoolClient, registry: ArtifactRegistry, input: ArtifactRegistrationInput, session: AgentSession, logger?: Logger): Promise<Result<ArtifactRegistrationResult, GateRefusal>>;

package/dist/execution/artifact-registration.js

@@ -9,7 +9,9 @@
  * (an external provenance ledger, or a filesystem index) is a composition-root
  * decision — this module never names one.
  */
+import { err, ok } from "neverthrow";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { passGate } from "../lib/hooks.js";
 import { upsertArtifacts, updateArtifactId } from "../state/index.js";
 // ── Registration ─────────────────────────────────────────────────────
 /**
@@ -18,6 +20,9 @@ import { upsertArtifacts, updateArtifactId } from "../state/index.js";
  * Builds the `cortex_artifacts` rows from the manifest, upserts them, then
  * delegates external provenance registration to the injected `ArtifactRegistry`
  * and applies any returned external ids back onto the local rows.
+ *
+ * A refusal of `register` writes no external id: the upserted rows keep
+ * `artifact_id = NULL`.
  */
 export async function registerStepArtifacts(db, registry, input, session, 
 // A parameter rather than a field on `ArtifactRegistrationInput`: that type is
@@ -27,7 +32,7 @@ logger = createNoopLogger()) {
     const { resourceId, runId, stepId, artifacts } = input;
     const log = logger.named("artifact-registration").with({ runId, stepId });
     if (artifacts.length === 0) {
-        return { localCount: 0, externalRegistered: 0, externalFailed: 0, failureDetails: [] };
+        return ok({ localCount: 0, externalRegistered: 0, externalFailed: 0, failureDetails: [] });
     }
     const dbPathPrefix = `runs/${runId}/${stepId}/`;
     const emptyHash = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
@@ -48,7 +53,10 @@ logger = createNoopLogger()) {
     });
     await upsertArtifacts(db, localEntries);
     const localPaths = new Set(localEntries.map((e) => e.path));
-    const result = await registry.register(input, session);
+    const registered = await passGate("ArtifactRegistry.register", registry.register(input, session));
+    if (registered.isErr())
+        return err(registered.error);
+    const result = registered.value;
     // The registry excluded these from `failed` by its own severity judgement, so
     // this is their only record. Logged here rather than left to the registry:
     // the seam is implementable by an embedder, and a rejection does not get to
@@ -67,10 +75,10 @@ logger = createNoopLogger()) {
         await updateArtifactId(db, resourceId, reg.path, reg.externalId);
         externalRegistered++;
     }
-    return {
+    return ok({
         localCount: localEntries.length,
         externalRegistered,
         externalFailed: result.failedCount,
         failureDetails: result.failed,
-    };
+    });
 }

package/dist/execution/artifact-registry.d.ts

@@ -14,9 +14,11 @@
  *   - `createNoopArtifactRegistry` (the harness, this dir) — registers nothing
  *     externally; the local `cortex_artifacts` ledger is the only record.
  */
+import type { ResultAsync } from "neverthrow";
 import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
 import type { ProvenanceCollector } from "../provenance/collector.js";
 import type { AgentSession } from "../auth/types.js";
+import type { GateFailure, NoticeFailure } from "../lib/hooks.js";
 /** High-level input for registering one step's artifacts. */
 export interface ArtifactRegistrationInput {
     /** Analysis resource ID. */
@@ -85,12 +87,17 @@ export interface ArtifactRegistry {
      * Implementations MUST NOT touch the local `cortex_artifacts` ledger — that
      * is the harness's responsibility, applied around this call. The `session` carries
      * the run credential an adapter needs to address the external system.
+     *
+     * A partial outcome is an `ok`, with the rejections in `failed`.
      */
-    register(input: ArtifactRegistrationInput, session: AgentSession): Promise<ExternalRegistrationResult>;
+    register(input: ArtifactRegistrationInput, session: AgentSession): ResultAsync<ExternalRegistrationResult, GateFailure>;
     /**
      * Push a step's registered artifacts to permanent storage. A no-op when the
      * adapter's bytes already live locally; the managed adapter uploads them.
-     * Throws on a persistent failure so the caller's fail-fast boundary fires.
+     *
+     * A notice (see `lib/hooks.ts`): an `err` is logged and does not fail the
+     * step. The rows stay unsynced, thus a later sync of the step selects them
+     * again.
      */
-    sync(input: ArtifactSyncInput, session: AgentSession): Promise<void>;
+    sync(input: ArtifactSyncInput, session: AgentSession): ResultAsync<void, NoticeFailure>;
 }

package/dist/execution/noop-artifact-registry.js

@@ -1,3 +1,4 @@
+import { okAsync } from "neverthrow";
 /**
  * Local/OSS artifact-registration seam: `register` records nothing externally
  * and reports zero failures; `sync` is a no-op. The harness writes the local
@@ -9,9 +10,7 @@
  */
 export function createNoopArtifactRegistry() {
     return {
-        async register() {
-            return { registered: [], failed: [], failedCount: 0 };
-        },
-        async sync() { },
+        register: () => okAsync({ registered: [], failed: [], failedCount: 0 }),
+        sync: () => okAsync(undefined),
     };
 }

package/dist/execution/post-step-pipeline.d.ts

@@ -10,12 +10,14 @@
  * the orchestration — which stage is `DBOS.runStep`-wrapped, which stage is
  * fail-fast vs. best-effort. This module owns only the stage bodies.
  */
+import { type Result } from "neverthrow";
 import type { Pool } from "pg";
 import type { AgentChat, EmbeddingProvider } from "../providers/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
 import type { StepSummary } from "../schemas/step-summary.js";
+import type { GateRefusal } from "../lib/hooks.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ArtifactRegistry } from "./artifact-registry.js";
@@ -53,17 +55,26 @@ export declare function generateStepFileMetadata(deps: PostStepPipelineDeps, pos
  * still returned for vector indexing.
  */
 export declare function generateStepSummaryAndWrite(deps: PostStepPipelineDeps, postCtx: PostStepContext, manifest: readonly ArtifactManifestEntry[]): Promise<StepSummary | undefined>;
+export type StepRegistrationFailure = {
+    readonly kind: "refused";
+    readonly refusal: GateRefusal;
+} | {
+    readonly kind: "rejected";
+    readonly message: string;
+};
+export declare function describeStepRegistrationFailure(failure: StepRegistrationFailure): string;
 /**
  * Reconcile the manifest against disk (drop phantoms, rehash) and register the
  * survivors with the local ledger + the injected `ArtifactRegistry`. Fail-fast
  * (see the artifact-manifest spec): `externalFailed` counts only the terminal
  * rejections — a rejected output whose bytes exist nowhere but the step tree,
  * plus anything rejected as a consequence of one — so a non-zero count means
- * real outputs went unregistered, and it throws with the per-file detail (the
- * OSS filesystem registry returns `externalFailed: 0`, so it never trips).
+ * real outputs went unregistered, and the `err` carries the per-file detail (the
+ * OSS filesystem registry returns `externalFailed: 0`, so it never trips). A
+ * refusal of the `register` gate is the other `err`.
  * Returns the reconciled manifest.
  */
-export declare function reconcileAndRegisterStepArtifacts(deps: PostStepPipelineDeps, postCtx: PostStepContext, manifest: readonly ArtifactManifestEntry[]): Promise<readonly ArtifactManifestEntry[]>;
+export declare function reconcileAndRegisterStepArtifacts(deps: PostStepPipelineDeps, postCtx: PostStepContext, manifest: readonly ArtifactManifestEntry[]): Promise<Result<readonly ArtifactManifestEntry[], StepRegistrationFailure>>;
 /**
  * Vector-index the threaded file descriptions + the step summary into the
  * per-analysis pgvector store. Best-effort (see the artifact-manifest spec):

package/dist/execution/post-step-pipeline.js

@@ -11,6 +11,7 @@
  * fail-fast vs. best-effort. This module owns only the stage bodies.
  */
 import { join } from "node:path";
+import { err, ok } from "neverthrow";
 import { unwrapOrThrow } from "../lib/result.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { writeFileWithinRoot } from "../lib/fs-helpers.js";
@@ -92,14 +93,18 @@ export async function generateStepSummaryAndWrite(deps, postCtx, manifest) {
     }
     return summary;
 }
+export function describeStepRegistrationFailure(failure) {
+    return failure.kind === "refused" ? `the artifact registry refused the registration: ${failure.refusal.reason}` : failure.message;
+}
 /**
  * Reconcile the manifest against disk (drop phantoms, rehash) and register the
  * survivors with the local ledger + the injected `ArtifactRegistry`. Fail-fast
  * (see the artifact-manifest spec): `externalFailed` counts only the terminal
  * rejections — a rejected output whose bytes exist nowhere but the step tree,
  * plus anything rejected as a consequence of one — so a non-zero count means
- * real outputs went unregistered, and it throws with the per-file detail (the
- * OSS filesystem registry returns `externalFailed: 0`, so it never trips).
+ * real outputs went unregistered, and the `err` carries the per-file detail (the
+ * OSS filesystem registry returns `externalFailed: 0`, so it never trips). A
+ * refusal of the `register` gate is the other `err`.
  * Returns the reconciled manifest.
  */
 export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest) {
@@ -115,14 +120,17 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
         ...(deps.logger ? { logger: deps.logger } : {}),
     });
     if (reconciled.manifest.length === 0)
-        return reconciled.manifest;
-    const reg = await registerStepArtifacts(deps.pool, deps.artifactRegistry, {
+        return ok(reconciled.manifest);
+    const registered = await registerStepArtifacts(deps.pool, deps.artifactRegistry, {
         resourceId: input.analysisId,
         runId: input.runId,
         stepId: input.stepId,
         artifacts: reconciled.manifest,
         collector: lineageCollector,
     }, session, deps.logger);
+    if (registered.isErr())
+        return err({ kind: "refused", refusal: registered.error });
+    const reg = registered.value;
     if (reg.externalFailed > 0) {
         // The registry commits per leaf and per activity, so accepted and rejected
         // rows arriving together is ordinary and `externalRegistered` is what
@@ -137,7 +145,7 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
             `${reg.externalFailed} terminal rejection(s), ${reg.externalRegistered}/${reg.localCount} local artifact(s) registered` +
             (noneRegistered ? " (nothing in this batch registered)" : "") +
             (detail ? `\n  ${detail}` : "");
-        // Logged as fields as well as thrown: the throw reaches `failStep` as one
+        // Logged as fields as well as returned: the failure reaches `failStep` as one
         // opaque string, so the per-path rejections are only queryable from here.
         // This is what distinguishes a registry rejection from the attestation
         // throws in `reconcileManifestWithDisk` when a step dies.
@@ -150,9 +158,9 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
             noneRegistered,
             failures: reg.failureDetails,
         });
-        throw new Error(msg);
+        return err({ kind: "rejected", message: msg });
     }
-    return reconciled.manifest;
+    return ok(reconciled.manifest);
 }
 /**
  * Vector-index the threaded file descriptions + the step summary into the
@@ -212,7 +220,12 @@ export async function vectorIndexStepOutputs(deps, postCtx, artifacts) {
     let indexed = 0;
     let failed = 0;
     for (const entry of liveMetadata) {
-        const ok = await indexOne(`/${input.analysisId}/${entry.dbPath}`, entry.description, { text: entry.description, type: "output", ...entry.metadata, path: entry.dbPath });
+        const ok = await indexOne(`/${input.analysisId}/${entry.dbPath}`, entry.description, {
+            text: entry.description,
+            type: "output",
+            ...entry.metadata,
+            path: entry.dbPath,
+        });
         if (ok)
             indexed++;
         else