@intx/hub-sessions 0.2.2 → 0.4.0

package/dist/workflow-kind.d.ts

@@ -9,13 +9,41 @@ export type WorkflowSidecarPrincipal = {
 export type WorkflowPrincipal = WorkflowHubPrincipal | WorkflowSidecarPrincipal;
 export declare const WORKFLOW_JSON_PATH = "workflow.json";
 export declare const CAPABILITY_DECLARATIONS_JSON_PATH = "capability-declarations.json";
-export declare const WORKFLOW_GITIGNORE_PATH = ".gitignore";
+export declare const PACKAGE_JSON_PATH = "package.json";
+export declare const NODE_MODULES_PATH = "node_modules";
+export declare const PNPM_WORKSPACE_PATH = "pnpm-workspace.yaml";
 export declare const workflowDefinitionEnvelopeSchema: import("arktype/internal/variants/object.ts").ObjectType<{
     id: string;
     triggers: unknown[];
     steps: Record<string, unknown>;
     stepOrder: string[];
     state?: Record<string, unknown>;
+    grantRequirements?: {
+        resource: string;
+        action: string;
+        source: "creator" | "invoker";
+        effect?: "allow" | "deny" | "ask";
+        conditions?: Record<string, unknown> | null;
+    }[];
+    credentialBindings?: {
+        package: string;
+        handle: string;
+        provider: string;
+        locator: "tenant";
+        name?: string;
+    }[];
+    sidecarPlacement?: {
+        capabilities?: {
+            capability: string;
+            effect: "require" | "block";
+        }[];
+    };
+    inboundMailPolicy?: {
+        untrustedFrom?: "reject" | "admit";
+        invalid?: "reject" | "admit";
+        missing?: "reject" | "admit";
+        unknown?: "reject" | "admit";
+    };
 }, {}>;
 export declare const workflowKindHandler: KindHandler;
 export declare const workflowAuthorize: AuthorizeFn;

package/dist/workflow-kind.js

@@ -1,18 +1,19 @@
 // KindHandler for the `workflow` asset kind.
 //
-// A workflow asset is a git repo that holds a single `WorkflowDefinition`
-// envelope plus its capability-walk output. The deploy tree shape is:
+// A workflow asset is a codebase: a top-level `package.json` declaring an
+// `interchange.workflow` entry module plus arbitrary source files. The sidecar
+// materializes the codebase into a closure and evaluates the pinned entry to the
+// definition. `validatePush` requires the `package.json`; a tree that lacks one
+// is rejected. The legacy `workflow.json` envelope form is no longer accepted at
+// the push boundary.
 //
-//   - `workflow.json` — the full `WorkflowDefinition` envelope. The
-//     content is parsed and structurally validated at push time; deeper
-//     primitive-shape and DAG validation belongs to the runtime layer
-//     that instantiates the definition (`defineWorkflow`).
-//   - `capability-declarations.json` — the per-step capability-walk
-//     output. Content shape is owned by the capability-walk module; the
-//     substrate only verifies the file parses as a JSON object.
-//   - `.gitignore` — supplied by the asset routes' genesis init body.
-//
-// Any top-level entry outside this set fails the push.
+// Source files are unconstrained, but the push validates the manifest's shape
+// and the entry-path's containment, and refuses an envelope-only
+// `capability-declarations.json`, a committed `node_modules`, and an ambiguous
+// tree that also carries an envelope-valid `workflow.json`, so one asset resolves
+// to exactly one definition. The codebase shape accepts both a single package and
+// a `workspaces` monorepo; for a monorepo the push validates only the root's
+// well-formedness and leaves per-member validation to the resolver.
 //
 // Authz:
 //   - hub principal: full access.
@@ -22,17 +23,16 @@
 //     used by skill assets.
 import { type } from "arktype";
 import { getLogger } from "@intx/log";
-import { glob, repoActionToGrantVerb } from "@intx/hub-common";
-import { UserPrincipal, } from "./repo-store/index.js";
+import { CredentialBinding, GrantRequirement, SidecarCapabilityPolicy, } from "@intx/types";
+import { InboundMailPolicy } from "@intx/types/runtime";
+import { PackageJSON, isContainedEntryPath } from "@intx/types/package-json";
+import { authorizeUserPrincipal, } from "./repo-store/index.js";
 const logger = getLogger(["hub-sessions", "workflow-kind"]);
 export const WORKFLOW_JSON_PATH = "workflow.json";
 export const CAPABILITY_DECLARATIONS_JSON_PATH = "capability-declarations.json";
-export const WORKFLOW_GITIGNORE_PATH = ".gitignore";
-const ALLOWED_TOP_LEVEL = new Set([
-    WORKFLOW_JSON_PATH,
-    CAPABILITY_DECLARATIONS_JSON_PATH,
-    WORKFLOW_GITIGNORE_PATH,
-]);
+export const PACKAGE_JSON_PATH = "package.json";
+export const NODE_MODULES_PATH = "node_modules";
+export const PNPM_WORKSPACE_PATH = "pnpm-workspace.yaml";
 /**
  * Structural arktype validator for the `workflow.json` envelope. The
  * substrate checks the cross-cutting shape of `WorkflowDefinition`
@@ -40,10 +40,10 @@ const ALLOWED_TOP_LEVEL = new Set([
  * `stepOrder`) but does not re-derive `defineWorkflow`'s DAG-level
  * validation here — primitive-level shape, default-input application,
  * and `after`-ref resolution belong to the runtime layer that hydrates
- * the definition. Push-time validation rejects the obvious wrongs
- * (missing top-level fields, wrong primitive types) so a tree that
- * could not possibly hydrate into a `WorkflowDefinition` never reaches
- * the deploy ref.
+ * the definition. The codebase push uses this validator to detect an
+ * ambiguous tree that also carries an envelope-valid `workflow.json`,
+ * and the hydrate-time definition loaders reuse it to validate a
+ * materialized definition before instantiation.
  */
 const StepsObject = type("Record<string, unknown>").narrow((value, ctx) => {
     if (Array.isArray(value)) {
@@ -63,20 +63,29 @@ export const workflowDefinitionEnvelopeSchema = type({
     steps: StepsObject,
     stepOrder: "string[]",
     "state?": StateObject,
+    // `grantRequirements` passes through the envelope whether or not it is
+    // declared here: arktype's `.onUndeclaredKey("ignore")` below is
+    // passthrough, not stripping (only `"delete"` strips), so the hydrate read
+    // sees the field either way. Declaring it here VALIDATES declared
+    // requirements at the deploy boundary — a malformed `source` is rejected
+    // rather than passed through unchecked — as defense in depth alongside the
+    // trigger route's own `GrantRequirements` re-validation. Compose the
+    // exported `GrantRequirement` arktype rather than restating its shape so the
+    // envelope and the definition stay in lockstep.
+    "grantRequirements?": GrantRequirement.array(),
+    // `credentialBindings` is validated here too -- same defense-in-depth
+    // rationale as grantRequirements above: a malformed binding (bad locator,
+    // authority, or handle) is rejected at the deploy boundary rather than
+    // passed through to launch-time resolution unchecked.
+    "credentialBindings?": CredentialBinding.array(),
+    "sidecarPlacement?": SidecarCapabilityPolicy,
+    // `inboundMailPolicy` is validated here too -- same defense-in-depth
+    // rationale as credentialBindings above: a malformed policy (an unknown
+    // outcome key or a value that is not reject/admit) is rejected at the deploy
+    // boundary rather than passed through to later admission resolution
+    // unchecked.
+    "inboundMailPolicy?": InboundMailPolicy,
 }).onUndeclaredKey("ignore");
-/**
- * Capability-declarations.json is held to "is a JSON object" at this
- * commit; the per-step structure is owned by the capability-walk
- * module that authors the file. `Record<string, unknown>` on its own
- * accepts arrays under arktype's structural-object semantics, so the
- * push validator pairs it with an array-rejection narrow.
- */
-const CapabilityDeclarationsObject = type("Record<string, unknown>").narrow((value, ctx) => {
-    if (Array.isArray(value)) {
-        return ctx.mustBe("a JSON object, not an array");
-    }
-    return true;
-});
 const SidecarPrincipal = type({
     kind: "'sidecar'",
     agentId: "string",
@@ -105,58 +114,99 @@ async function readJSONBlob(path, readBlob) {
     }
     return { ok: true, value: parsed };
 }
+function isJSONObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function rejectPush(repoId, ref, reason) {
+    logger.debug `workflow validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${reason}`;
+    return { ok: false, reason };
+}
+/**
+ * Validate the codebase shape: a top-level `package.json` declaring a contained
+ * `interchange.workflow` entry (single package), or a `workspaces` monorepo
+ * whose root well-formedness is checked and whose members are deferred to the
+ * resolver, plus arbitrary source files. Entered when the tree carries a
+ * `package.json`. Source files are unconstrained, but the push refuses the
+ * envelope-only `capability-declarations.json`, a committed `node_modules`, and
+ * an ambiguous tree that also carries an envelope-valid `workflow.json`, so one
+ * asset resolves to exactly one definition.
+ *
+ * The push validates STRUCTURE only. It never imports or evaluates the entry
+ * module -- that runs author code and is the sidecar's sandboxed job. The
+ * entry-path containment check is the string-level half of the loader's rule
+ * (`isContainedEntryPath`); the realpath-based symlink half runs at load time
+ * against the materialized directory, which the hub does not have here.
+ */
+async function validateWorkflowCodebasePush(repoId, ref, topLevelTreePaths, readBlob) {
+    if (topLevelTreePaths.includes(CAPABILITY_DECLARATIONS_JSON_PATH)) {
+        return rejectPush(repoId, ref, `${CAPABILITY_DECLARATIONS_JSON_PATH} is an envelope-only artifact and cannot appear in a codebase workflow asset`);
+    }
+    if (topLevelTreePaths.includes(NODE_MODULES_PATH)) {
+        return rejectPush(repoId, ref, `a committed top-level ${NODE_MODULES_PATH} directory is not allowed; the sidecar materializes dependencies from the resolved closure`);
+    }
+    // A `workflow.json` that also parses as a valid envelope makes the asset
+    // advertise two definitions; reject that. A `workflow.json` present but not a
+    // valid envelope is an ordinary source file and is allowed.
+    if (topLevelTreePaths.includes(WORKFLOW_JSON_PATH)) {
+        const envelopeOutcome = await readJSONBlob(WORKFLOW_JSON_PATH, readBlob);
+        if (envelopeOutcome.ok &&
+            !(workflowDefinitionEnvelopeSchema(envelopeOutcome.value) instanceof
+                type.errors)) {
+            return rejectPush(repoId, ref, `tree carries both ${PACKAGE_JSON_PATH} and an envelope-valid ${WORKFLOW_JSON_PATH}; a workflow asset must be a codebase or an envelope, not both`);
+        }
+    }
+    const pkgOutcome = await readJSONBlob(PACKAGE_JSON_PATH, readBlob);
+    if (!pkgOutcome.ok) {
+        return rejectPush(repoId, ref, pkgOutcome.reason);
+    }
+    // `PackageJSON` does not declare `workspaces`, so it is read off the raw
+    // parsed value. A monorepo is a distinct codebase shape: the workflow lives
+    // in one member, selected at resolve time by `packageName`, so this gate does
+    // NOT descend into members or require a root `interchange.workflow`. It
+    // validates ROOT well-formedness only -- `workspaces` is an array of glob
+    // strings -- and defers per-member validation to the resolver, which re-reads
+    // every member and fails loud there (one enumeration owner, not two).
+    if (isJSONObject(pkgOutcome.value) && "workspaces" in pkgOutcome.value) {
+        const workspaces = pkgOutcome.value["workspaces"];
+        if (!Array.isArray(workspaces) ||
+            !workspaces.every((w) => typeof w === "string")) {
+            return rejectPush(repoId, ref, `${PACKAGE_JSON_PATH} "workspaces" must be an array of glob strings; the object form ({ packages, catalog, catalogs }) is not supported`);
+        }
+        return { ok: true };
+    }
+    // A pnpm monorepo declares its members in `pnpm-workspace.yaml`, not the
+    // package.json `workspaces` field, so a pnpm root has no `workspaces` and
+    // would fall through to the single-package check below. Reject that layout at
+    // the boundary with a clear message rather than letting it fail obscurely at
+    // resolve time (full pnpm support is tracked in INTR-461).
+    if (topLevelTreePaths.includes(PNPM_WORKSPACE_PATH)) {
+        return rejectPush(repoId, ref, `tree declares a ${PNPM_WORKSPACE_PATH}; the pnpm workspace layout is not supported -- declare members via a package.json "workspaces" array`);
+    }
+    const pkg = PackageJSON(pkgOutcome.value);
+    if (pkg instanceof type.errors) {
+        return rejectPush(repoId, ref, `${PACKAGE_JSON_PATH} failed validation: ${pkg.summary}`);
+    }
+    const entry = pkg.interchange?.workflow;
+    if (entry === undefined || entry === "") {
+        return rejectPush(repoId, ref, `${PACKAGE_JSON_PATH} must declare a non-empty "interchange.workflow" entry`);
+    }
+    if (!isContainedEntryPath(entry)) {
+        return rejectPush(repoId, ref, `"interchange.workflow" entry ${JSON.stringify(entry)} must be a package-relative path that does not escape the package`);
+    }
+    return { ok: true };
+}
 export const workflowKindHandler = {
     kind: "workflow",
     directoryPrefix: "assets/workflow",
     async validatePush({ repoId, ref, topLevelTreePaths, readBlob, }) {
-        for (const entry of topLevelTreePaths) {
-            if (!ALLOWED_TOP_LEVEL.has(entry)) {
-                return {
-                    ok: false,
-                    reason: `unexpected top-level entry ${JSON.stringify(entry)}; allowed: "${WORKFLOW_JSON_PATH}", "${CAPABILITY_DECLARATIONS_JSON_PATH}", "${WORKFLOW_GITIGNORE_PATH}"`,
-                };
-            }
-        }
-        // A workflow asset without `workflow.json` is structurally
-        // incoherent: there is nothing for the deploy orchestrator to
-        // hydrate. Reject so the push surfaces the missing envelope at
-        // the boundary rather than at hydrate time.
-        if (!topLevelTreePaths.includes(WORKFLOW_JSON_PATH)) {
-            return {
-                ok: false,
-                reason: `tree is missing required ${WORKFLOW_JSON_PATH}`,
-            };
-        }
-        const workflowOutcome = await readJSONBlob(WORKFLOW_JSON_PATH, readBlob);
-        if (!workflowOutcome.ok) {
-            logger.debug `workflow validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${workflowOutcome.reason}`;
-            return { ok: false, reason: workflowOutcome.reason };
-        }
-        const validated = workflowDefinitionEnvelopeSchema(workflowOutcome.value);
-        if (validated instanceof type.errors) {
-            const reason = `${WORKFLOW_JSON_PATH} failed validation: ${validated.summary}`;
-            logger.debug `workflow validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${reason}`;
-            return { ok: false, reason };
+        if (topLevelTreePaths.includes(PACKAGE_JSON_PATH)) {
+            return validateWorkflowCodebasePush(repoId, ref, topLevelTreePaths, readBlob);
         }
-        if (topLevelTreePaths.includes(CAPABILITY_DECLARATIONS_JSON_PATH)) {
-            const capOutcome = await readJSONBlob(CAPABILITY_DECLARATIONS_JSON_PATH, readBlob);
-            if (!capOutcome.ok) {
-                logger.debug `workflow validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${capOutcome.reason}`;
-                return { ok: false, reason: capOutcome.reason };
-            }
-            const capValidated = CapabilityDeclarationsObject(capOutcome.value);
-            if (capValidated instanceof type.errors) {
-                const reason = `${CAPABILITY_DECLARATIONS_JSON_PATH} must be a JSON object: ${capValidated.summary}`;
-                logger.debug `workflow validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${reason}`;
-                return { ok: false, reason };
-            }
-        }
-        return { ok: true };
+        return rejectPush(repoId, ref, `a workflow asset must be a codebase declaring a ${PACKAGE_JSON_PATH} with an "interchange.workflow" entry; the ${WORKFLOW_JSON_PATH} envelope form is no longer supported`);
     },
     onRefUpdated() {
-        // No cached index today. Consumers read the workflow.json and
-        // capability-declarations.json through the substrate's blob-read
-        // API at session time.
+        // No cached index today. Consumers read the asset's tree through the
+        // substrate's blob-read API at session time.
     },
 };
 export const workflowAuthorize = (principal, repoId, ref, action) => {
@@ -198,64 +248,18 @@ export const workflowAuthorize = (principal, repoId, ref, action) => {
         }
     }
     if (principal.kind === "user") {
-        // The route layer has already pre-resolved the grant verdict and
-        // attached it as `authz`. The substrate does NOT re-query the
-        // grant store here; it (a) checks the bearer-token's claims
-        // bound the requested (ref, action) and have not expired, and
-        // (b) sanity-checks that the pre-resolved verdict targets this
-        // exact resource and grant verb. Both gates must pass before the
-        // verdict's `effect` is honoured.
-        const parsed = UserPrincipal(principal);
-        if (parsed instanceof type.errors) {
-            return {
-                allowed: false,
-                reason: `user principal is malformed: ${parsed.summary}`,
-            };
-        }
-        if (!parsed.tokenClaims.actions.includes(action)) {
-            return {
-                allowed: false,
-                reason: `token does not grant action ${action}`,
-            };
-        }
-        // `ref === "*"` is the substrate's sentinel for the bulk read
-        // performed by `listRefs`. Per-ref filtering is the advertise-refs
-        // layer's responsibility, so the bulk read is gated on action and
-        // expiry alone.
-        if (ref !== "*" && !glob.match(parsed.tokenClaims.refPattern, ref)) {
-            return {
-                allowed: false,
-                reason: `token refPattern ${parsed.tokenClaims.refPattern} does not match ${ref}`,
-            };
-        }
-        if (Date.now() >= parsed.tokenClaims.expiresAt) {
-            return {
-                allowed: false,
-                reason: `token expired at ${parsed.tokenClaims.expiresAt}`,
-            };
-        }
-        const expectedResource = `asset:${repoId.id}`;
-        if (parsed.authz.resource !== expectedResource) {
-            return {
-                allowed: false,
-                reason: `authz verdict resource ${parsed.authz.resource} does not match ${expectedResource}`,
-            };
-        }
-        const expectedGrantVerb = repoActionToGrantVerb(action);
-        if (parsed.authz.grantVerb !== expectedGrantVerb) {
-            return {
-                allowed: false,
-                reason: `authz verdict grantVerb ${parsed.authz.grantVerb} does not match ${expectedGrantVerb}`,
-            };
-        }
-        if (parsed.authz.effect === "allow") {
-            return { allowed: true };
-        }
-        return {
-            allowed: false,
-            reason: `authz verdict denied for ${expectedResource} ${expectedGrantVerb}`,
-        };
+        return authorizeUserPrincipal({
+            principal,
+            repoId,
+            ref,
+            action,
+            resourcePrefix: "asset",
+        });
     }
+    // Fail closed on any kind not handled above. The tenant-level
+    // `workflow` principal kind (`@intx/types` principalKinds) is a
+    // grant owner, not a git/asset bearer, and never carries a workflow
+    // repo push here -- so it is intentionally left denied.
     return {
         allowed: false,
         reason: `unknown principal kind: ${principal.kind}`,

package/dist/workflow-probe-gate.d.ts

@@ -0,0 +1,286 @@
+import type { DBExecutor } from "@intx/db";
+import type { ApprovalItem, GrantRequirement, GrantWalkSnapshot } from "@intx/types";
+import type { PackumentFetcher, RegistryConfig } from "@intx/tool-packaging";
+import type { WorkflowProjectionDefinition } from "@intx/types/sidecar";
+import type { ToolPackageManifest } from "@intx/types/tool-packages";
+import type { WorkflowDefinitionAssetSource, WorkflowDefinitionRegistrySource } from "@intx/types/workflow-sources";
+import { type ApprovalSet } from "@intx/workflow-deploy";
+import { type ResolveAssetAttachmentFn } from "./workflow-closure-resolution.js";
+import type { SourceTreeReads } from "./workflow-source-closure.js";
+import type { SendProbeArgs, WorkflowProbeResult } from "./ws/sidecar-handler.js";
+type WorkflowProbeRouter = {
+    sendProbe(args: SendProbeArgs): Promise<WorkflowProbeResult>;
+};
+/**
+ * The frozen record an approval writes: the definition's asset selector, the
+ * approved wire hash (the freeze anchor), the approved surface, and the
+ * grant-walk snapshot the run path materializes grants from. The approved
+ * surface is a deterministic projection of the content the hash addresses and
+ * rides the deploy hand-off in memory; the snapshot is persisted onto the
+ * version row so a run derives its grants from the frozen walk without
+ * re-reading and re-walking the workflow's `workflow.json`.
+ *
+ * `approvedGrants` carries both kinds of approved item: the walk's grant-shape
+ * strings and the definition's declared grant requirements. The requirements
+ * belong in the same record because the run path mints real grant rows from
+ * them, so an account of the approval that listed only the walk strings would
+ * under-report the authority the definition will actually carry. It is the flat
+ * `ApprovalItem` list rather than the gate's partitioned `ApprovalSet` because
+ * this record is the input to persistence, and the persisted form is flat.
+ */
+export type FrozenApproval = {
+    readonly assetId: string;
+    readonly approvedWireHash: string;
+    readonly approvedGrants: readonly ApprovalItem[];
+    readonly grantSnapshot: GrantWalkSnapshot;
+};
+/**
+ * Persists a frozen approval and returns the definition it was recorded
+ * against. Bound to a `DBExecutor` in production via
+ * `createDbFrozenApprovalWriter`; a test double records the call.
+ */
+export type PersistFrozenApprovalFn = (approval: FrozenApproval) => Promise<{
+    definitionId: string;
+}>;
+/**
+ * The outcome of gating and freezing a probe result. `ok: true` is the frozen
+ * approval the deploy hand-off consumes. The `ok: false` arms name the five
+ * fail-closed paths: a shipped hash that does not match the hub recompute
+ * (tamper-evidence), advisory grants the operator did not approve, declared
+ * grant requirements the operator did not approve, a trigger type the runtime
+ * does not implement, and an executable step the grant walk left no record for.
+ */
+export type ProbeGateResult = {
+    readonly ok: true;
+    readonly definitionId: string;
+    readonly approvedWireHash: string;
+    readonly approvedSurface: ApprovalSet;
+    /**
+     * The inert wire projection the freeze hashed. Rides the ok-arm so the
+     * deploy hand-off carries the exact content the frozen hash addresses,
+     * never a re-projection of a registry that may have moved since approval.
+     */
+    readonly projection: WorkflowProjectionDefinition;
+} | {
+    readonly ok: false;
+    readonly reason: "wire_hash_mismatch";
+    readonly shippedWireHash: string;
+    readonly recomputedWireHash: string;
+} | {
+    readonly ok: false;
+    readonly reason: "grants_not_approved";
+    readonly unapprovedGrants: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: "grant_requirements_not_approved";
+    /**
+     * The declared requirements the operator's approval does not cover, in
+     * the order the probe declared them. Named in full so the operator can
+     * see exactly which authority the definition asked to delegate.
+     */
+    readonly unapprovedGrantRequirements: readonly GrantRequirement[];
+} | {
+    readonly ok: false;
+    readonly reason: "unimplemented_trigger";
+    /** The distinct reserved-but-unimplemented trigger types the projection declared. */
+    readonly unimplementedTriggerTypes: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: "steps_without_grant_record";
+    /** Every executable step the grant-walk snapshot accounts for nothing at. */
+    readonly stepsWithoutGrantRecord: readonly StepWithoutGrantRecord[];
+    /**
+     * One sentence naming every miss. A deploy that trips this is a defect in
+     * the deploy path rather than in the author's workflow, so the sentence
+     * carries what whoever maintains that path needs: the step, the position,
+     * and the record that was absent.
+     */
+    readonly message: string;
+};
+/**
+ * One step the deployment can execute that the probe's grant-walk snapshot
+ * carries no record for.
+ */
+export type StepWithoutGrantRecord = {
+    /** The executable step id with no approved grants behind it. */
+    readonly stepId: string;
+    /**
+     * The chain of step ids the executable walk reached `stepId` through,
+     * outermost first and `stepId` itself last. Two nested bodies may
+     * legitimately carry the same step id, so the chain -- not the id alone --
+     * is what names the position in the closure.
+     */
+    readonly reachedThrough: readonly string[];
+    /**
+     * The top-level step whose snapshot record was supposed to account for
+     * `stepId`. The capability walk folds every nested body's grants into the
+     * record of the top-level step that carries the body, so this names the
+     * `perStep` key the absent record would have had.
+     */
+    readonly recordStepId: string;
+};
+/**
+ * Build the production persistence step of the freeze. Records identity through
+ * the selector-keyed ensure helper (a definition keyed by `(assetId,
+ * wireHash)`) and writes the approved wire hash and the grant-walk snapshot onto
+ * that definition's version row in one transaction. The grant SET is not written
+ * to a version-row column -- the approved wire hash already pins the content the
+ * grants project from -- so it travels with the returned frozen approval; the
+ * snapshot is written because the run path reads it back to materialize grants.
+ */
+export declare function createDbFrozenApprovalWriter(db: DBExecutor): PersistFrozenApprovalFn;
+/**
+ * Approve exactly the grant surface the probe reports, without a pre-walked
+ * operator `ApprovalSet` to gate against. Under this mode the gate skips the
+ * per-grant and per-requirement membership checks and freezes exactly what the
+ * probe advertised.
+ *
+ * This is the code-sourced analogue of the live-authored self-approve: the hub
+ * has no live definition to pre-walk, so the probe's advertised grants ARE the
+ * declared surface. It does NOT relax tamper-evidence -- the wire-hash check
+ * still runs and can still fail closed.
+ */
+export type ApproveProbedGrants = {
+    readonly kind: "approve-probed";
+};
+/**
+ * How the gate turns the probe's advertised surface into an approved one.
+ * Either an explicit operator `ApprovalSet` -- every advertised grant and every
+ * declared grant requirement must appear in it or the gate fails closed -- or
+ * `approve-probed`, which approves exactly the surface the probe reported.
+ */
+export type ProbeApprovalPolicy = ApprovalSet | ApproveProbedGrants;
+export type GateAndFreezeArgs = {
+    /** The `workflow`-kind asset the frozen definition projects over. */
+    readonly assetId: string;
+    /** The sidecar's inert probe answer: projection, advisory grants, shipped hash. */
+    readonly probeResult: WorkflowProbeResult;
+    /**
+     * The approval policy. An `ApprovalSet` gates the advisory set and the
+     * declared grant requirements against the operator-approved items;
+     * `approve-probed` approves exactly the surface the probe reported.
+     */
+    readonly approvals: ProbeApprovalPolicy;
+    /** Persistence step for the freeze; `createDbFrozenApprovalWriter` in production. */
+    readonly persist: PersistFrozenApprovalFn;
+};
+/**
+ * Gate a probe result and, on approval, freeze it. Operates purely over the
+ * inert projection and grant set -- no author code runs here and the capability
+ * walk is never re-run.
+ *
+ * Fails closed on the three security-load-bearing checks before it writes
+ * anything: the recomputed wire hash must match the hash the sidecar shipped
+ * (tamper-evidence), every advisory grant must be operator-approved, and every
+ * declared grant requirement must be operator-approved. It also refuses a
+ * projection whose triggers include a reserved-but-unimplemented type -- not a
+ * security check, but the layer a pinned closure cannot carry a stale copy of,
+ * so it is where a workflow that could only sit inert is caught -- and one
+ * whose executable closure reaches a step the grant walk left no record for --
+ * the layer holding both halves of the probe answer at once, and a presence
+ * check on those records rather than a check that any record's contents are
+ * sufficient.
+ * Only then does it freeze the recomputed hash onto the version row and return
+ * the approved grant set.
+ */
+export declare function gateAndFreezeProbeResult(args: GateAndFreezeArgs): Promise<ProbeGateResult>;
+type InstallAndApproveCommonArgs = {
+    /** The `interchange.workflow` entry-module path the sidecar evaluates to project the definition. */
+    readonly entry: string;
+    /** The `workflow`-kind asset the frozen definition projects over. */
+    readonly assetId: string;
+    /**
+     * The approval policy threaded to the gate: an operator `ApprovalSet` to gate
+     * the advisory set against, or `approve-probed` to approve exactly the
+     * surface the probe reports.
+     */
+    readonly approvals: ProbeApprovalPolicy;
+    /** The sidecar router carrying the probe transport. */
+    readonly router: WorkflowProbeRouter;
+    /** Executor the freeze writes through. */
+    readonly db: DBExecutor;
+    /** Optional durable handoff invoked before the approval gate writes. */
+    readonly onProbeResult?: (result: WorkflowProbeResult) => Promise<void>;
+};
+/** Install a definition published to an npm registry. */
+export type InstallAndApproveRegistryArgs = InstallAndApproveCommonArgs & {
+    readonly source: WorkflowDefinitionRegistrySource;
+    /** A `name@range` spec for the workflow definition package. */
+    readonly pin: string;
+    /** URL and credentials for the registry `source` names. */
+    readonly registryConfig: RegistryConfig;
+    /** Test seam for packument fetches, threaded to closure resolution. Omitted in production. */
+    readonly fetchPackument?: PackumentFetcher;
+};
+/**
+ * Install a definition published as a tarball inside a hub `package-registry`
+ * asset. The caller mints the asset-read closures (`readBlob`/`listBlobs`) and
+ * `resolveAttachment`; this glue never imports the asset service, so hub-service
+ * ownership stays at the caller.
+ */
+export type InstallAndApproveAssetTarballArgs = InstallAndApproveCommonArgs & {
+    readonly source: WorkflowDefinitionAssetSource;
+    /** A `name@range` spec for the workflow definition package. */
+    readonly pin: string;
+    /** Reads a blob at `path` from the asset the definition is sourced from. */
+    readonly readBlob: (path: string) => Promise<Uint8Array>;
+    /** Lists the blob names directly under `dir` in that asset. */
+    readonly listBlobs: (dir: string) => Promise<string[]>;
+    /** Resolves each asset the closure references to the pack the probe delivers. */
+    readonly resolveAttachment: ResolveAssetAttachmentFn;
+};
+/**
+ * Install a definition whose package lives as a git subtree of a hub asset at a
+ * pinned commit. The caller binds a `SourceTreeReads` to that commit and
+ * supplies the npm `registryConfig` for the external deps; there is no
+ * `name@range` pin (the member is selected from `source.package.packageName`).
+ * `resolveAttachment` delivers the same git pack the tarball arm does, so the
+ * sidecar checks the subtree out of it.
+ */
+export type InstallAndApproveAssetSourceArgs = InstallAndApproveCommonArgs & {
+    readonly source: WorkflowDefinitionAssetSource;
+    /** Git-tree reads pinned to `source.package.commitSha`. */
+    readonly reads: SourceTreeReads;
+    /**
+     * The registry name external deps are stamped with in the frozen closure.
+     * Must be a name the sidecar's registry map is keyed by (its npm registry).
+     */
+    readonly registryName: string;
+    /** URL and credentials for the npm registry external deps resolve against. */
+    readonly registryConfig: RegistryConfig;
+    /** Test seam for packument fetches, threaded to closure resolution. Omitted in production. */
+    readonly fetchPackument?: PackumentFetcher;
+    /** Resolves each asset the closure references to the pack the probe delivers. */
+    readonly resolveAttachment: ResolveAssetAttachmentFn;
+};
+export type InstallAndApproveArgs = InstallAndApproveRegistryArgs | InstallAndApproveAssetTarballArgs | InstallAndApproveAssetSourceArgs;
+/**
+ * The frozen hand-off `installAndApproveWorkflowDefinition` produces. It carries
+ * the gate outcome plus the two values the source-ref deploy frame needs and
+ * must NOT recompute at deploy: the inert `projection` the freeze hashed and the
+ * frozen dependency `closure` the pin resolved to. Re-resolving either at deploy
+ * would reintroduce the non-determinism the freeze eliminates -- a registry that
+ * moved between approve and deploy would pin different bytes and project
+ * differently, failing the child re-verify -- so both ride from approve verbatim.
+ */
+export type InstallAndApproveResult = {
+    readonly approval: ProbeGateResult;
+    readonly projection: WorkflowProjectionDefinition;
+    readonly closure: ToolPackageManifest;
+};
+/**
+ * The install/approve orchestration entrypoint the end-to-end flow drives:
+ * resolve the frozen closure, probe the sidecar, then gate and freeze the
+ * result. This is production glue, not test-only wiring.
+ *
+ * The operator-approval decision is an input (`approvals`): the caller supplies
+ * either the `ApprovalSet` the operator approved, which the gate holds the
+ * advisory set to, or `approve-probed` to approve exactly the surface the probe
+ * reports.
+ *
+ * Returns the gate outcome alongside the inert projection and the frozen
+ * closure so the deploy hand-off consumes them verbatim rather than re-probing
+ * or re-resolving.
+ */
+export declare function installAndApproveWorkflowDefinition(args: InstallAndApproveArgs): Promise<InstallAndApproveResult>;
+export {};