@intx/hub-sessions 0.2.2 → 0.3.0

package/dist/repo-store/types.d.ts

@@ -80,14 +80,18 @@ export type AuthorizeFn = (principal: Principal, repoId: RepoId, ref: string, ac
  * commit under validation -- present in the prospective tree and absent from
  * the prior tree. The kind handler authoritatively detects this during its
  * validation walk and surfaces it so callers do not re-derive terminal-ness
- * by sniffing committed path shapes. `terminalEventJson` carries the raw bytes
- * of the terminal event blob so a caller can reconstruct the event without a
- * second read. A commit that carries an already-terminal run forward
- * unchanged (e.g. a later compaction commit) is NOT newly terminal and does
- * not appear here.
+ * by sniffing committed path shapes. `status` is the terminal run state the
+ * terminal event maps to, matching the `workflow_run.status` vocabulary, so a
+ * caller flips the run's row without re-parsing the event type.
+ * `terminalEventJson` carries the raw bytes of the terminal event blob so a
+ * caller that needs the full event (the supervisor's terminal-write broadcast)
+ * can reconstruct it without a second read. A commit that carries an
+ * already-terminal run forward unchanged (e.g. a later compaction commit) is
+ * NOT newly terminal and does not appear here.
  */
 export type NewlyTerminalRun = {
     runId: string;
+    status: "completed" | "failed" | "cancelled";
     terminalEventJson: string;
 };
 export type ValidatePushResult = {
@@ -315,6 +319,48 @@ export interface KindHandler {
         newSha: string;
     }) => Promise<void> | void;
 }
+/**
+ * A single child entry returned by `CommittedReads.listDir`. `name` is
+ * the entry's own path segment (no parent prefix); `oid` is its git
+ * object id; `type` is the git tree-entry kind. `oid` lets a consumer
+ * read a blob's bytes via `readBlobByOid` without re-resolving the path,
+ * and lets it prove a subtree byte-unchanged by OID equality.
+ */
+export type CommittedTreeEntry = {
+    readonly name: string;
+    readonly oid: string;
+    readonly type: "blob" | "tree" | "commit";
+};
+/**
+ * Cache-backed reads pinned to the commit a ref resolved to at the
+ * moment `openCommittedReads` was called. Every read resolves against
+ * the git object store, never the materialized working tree, so a
+ * consumer observes committed state even when the on-disk checkout lags
+ * the committed tree. The pin is fixed at open time: a concurrent commit
+ * that advances the ref afterwards does not shift the reads, so an
+ * enumerate-then-read sequence sees a single coherent snapshot.
+ *
+ * `listDir` returns the direct children of a repo-root-relative POSIX
+ * directory path (no leading or trailing slash; the empty string lists
+ * the root). A path that is absent, or resolves to a non-tree, lists as
+ * the empty array — mirroring the prior-tree closures the substrate
+ * hands a kind handler. `readBlobByOid` reads a blob's bytes by its
+ * object id; a read fault surfaces as a thrown error rather than an
+ * empty result so a consumer cannot silently degrade a missing object
+ * into an absent event.
+ */
+export type CommittedReads = {
+    listDir(relPath: string): Promise<CommittedTreeEntry[]>;
+    readBlobByOid(oid: string): Promise<Uint8Array>;
+    /**
+     * The git tree object id of the subtree at `relPath` (the empty string
+     * or "." is the commit's root tree), or `null` when `relPath` is absent
+     * or resolves to a non-tree. This is the content identity a source
+     * closure freezes for a package materialized from the tree: the sidecar
+     * re-checks the checked-out subtree against it.
+     */
+    treeOid(relPath: string): Promise<string | null>;
+};
 export interface RepoStore {
     /**
      * Bookkeeping primitive. Idempotent. Creates the repo directory
@@ -368,8 +414,16 @@ export interface RepoStore {
      * via `resolveRef` first; the substrate exposes no force-write
      * mode because silently overwriting a losing concurrent update is
      * never the right behavior.
+     *
+     * Returns the runs the received pack drove to a terminal event,
+     * aggregated across every commit it carried. The kind handler
+     * detects terminal-ness authoritatively during validation; the
+     * substrate forwards it so a caller can react (flip the run's DB
+     * row, deactivate its principal) without re-deriving terminal-ness
+     * from the committed path shape. Empty for kinds and packs that
+     * produce none.
      */
-    receivePack(principal: Principal, repoId: RepoId, ref: string, pack: Uint8Array, commitSha: string, expectedOldSha: string | null): Promise<void>;
+    receivePack(principal: Principal, repoId: RepoId, ref: string, pack: Uint8Array, commitSha: string, expectedOldSha: string | null): Promise<NewlyTerminalRun[]>;
     createPack(principal: Principal, repoId: RepoId, ref: string): Promise<{
         pack: Uint8Array;
         commitSha: string;
@@ -425,6 +479,40 @@ export interface RepoStore {
      * they reach into for ref-listing and pack negotiation.
      */
     getRepoDir(repoId: RepoId): string;
+    /**
+     * Open cache-backed reads of the committed tree at `ref`'s tip. The
+     * ref is resolved once, at call time, and every read the returned
+     * handle serves is pinned to that commit and resolves through the git
+     * object store — not the materialized working tree `getRepoDir` points
+     * at. A consumer that must observe committed state (e.g. start-time
+     * recovery reconstructing a ledger from the persisted log) reads
+     * through this rather than the working tree, which a non-atomic
+     * post-commit materialization can leave lagging on a contended
+     * filesystem.
+     *
+     * Gated under the same `resolveRef` action as `resolveRef` / `listRefs`
+     * / `subscribe`. Returns `null` when the repo does not yet exist
+     * (mirrors `listRefs`'s empty-list contract for uninitialised repos)
+     * or when `ref` does not resolve to a commit.
+     */
+    openCommittedReads(principal: Principal, repoId: RepoId, ref: string): Promise<CommittedReads | null>;
+    /**
+     * Open cache-backed reads of the committed tree at an explicit commit,
+     * the by-SHA counterpart of `openCommittedReads`. A consumer that
+     * already holds a commit id — e.g. the `newSha`/`oldSha` of a
+     * ref-update event it is diffing — reads that exact commit through
+     * this, even after the ref has advanced past it. Every read the handle
+     * serves resolves through the git object store, pinned to `commitSha`.
+     *
+     * Gated under the same `resolveRef` action as `openCommittedReads`.
+     * `commitSha` is validated at the boundary: a malformed SHA throws
+     * `commit_sha_invalid`. Returns `null` when the repo does not yet exist
+     * or when `commitSha` names no commit in the object store (a commit a
+     * concurrent GC pruned between the caller learning of it and reading
+     * it), so a caller diffing a possibly-vanished commit gets an empty
+     * view rather than a mid-walk throw.
+     */
+    openCommittedReadsAtCommit(principal: Principal, repoId: RepoId, commitSha: string): Promise<CommittedReads | null>;
     /**
      * Tail a ref's commit log. Returns an async iterator that emits
      * `{ seq, event }` entries: one per commit on the ref. `seq` is

package/dist/session-service.d.ts

@@ -1,12 +1,17 @@
 import { type DB } from "@intx/db";
+import type { CredentialDelivery } from "@intx/types/sidecar";
+import type { CredentialCipher } from "@intx/types";
 import type { CryptoProvider, HarnessConfig, InferenceSource, MessageAttachment } from "@intx/types/runtime";
 import { type RegistryConfig, type ScopeRoute } from "@intx/tool-packaging";
 import { type ToolPackagePin } from "@intx/types/tool-packages";
-import { type WorkflowDefinition } from "@intx/workflow/definition";
-import { type DeployContent as OrchestratorDeployContent, type DeploySingleStepFn } from "@intx/workflow-deploy";
+import type { SourceRefPin, WorkflowProjectionWithSources, WorkflowSourceAssetMount } from "@intx/types/sidecar";
+import type { WorkflowDefinitionAssetSource, WorkflowDefinitionRegistrySource, WorkflowDefinitionSource } from "@intx/types/workflow-sources";
+import { type DeployContent as OrchestratorDeployContent } from "@intx/workflow-deploy";
 import type { AgentRepoStore, DeployContent } from "./agent-repo.js";
 import { type AssetService } from "./asset-service.js";
-import type { SidecarRouter } from "./ws/sidecar-handler.js";
+import type { AllocatedSidecarTarget, SidecarAllocationRouter, SidecarRouter } from "./ws/sidecar-handler.js";
+import { type ResolveAssetAttachmentFn } from "./workflow-closure-resolution.js";
+import { type InstallAndApproveResult } from "./workflow-probe-gate.js";
 export declare class SessionLaunchError extends Error {
     /** Which phase failed: "write", "provision", "pack", or "start". */
     readonly phase: string;
@@ -27,58 +32,33 @@ export type SessionService = {
     stageWorkflowStep(params: {
         agentAddress: string;
         agentId: string;
-        instanceId: string;
+        runId: string;
         config: HarnessConfig;
         deployContent: DeployContent;
         toolPackagePins?: readonly ToolPackagePin[];
+        allocationTarget?: AllocatedSidecarTarget;
     }): Promise<void>;
     /**
-     * Deploy a single-agent instance through the single-step-at-head path,
-     * wrapping the harness as a one-step workflow and routing it through the
-     * deploy core with the instance's real identity. Replaces `launchSession`
-     * as the production instance-deploy entry point: the instance runs as a
-     * supervised workflow-process child. Writes no `workflow_deployment`
-     * row. Returns the head's agent-key ack (the key the head signs its
-     * reconnect challenges with).
-     */
-    deployInstanceAtHead(params: {
-        agentAddress: string;
-        agentId: string;
-        instanceId: string;
-        config: HarnessConfig;
-        deployContent: DeployContent;
-        toolPackagePins?: readonly ToolPackagePin[];
-    }): Promise<{
-        publicKey: string;
-    }>;
-    /**
-     * Deploy a one-step workflow once at the head through the deploy core,
-     * without the DB-backed `workflow_deployment` projection row. Stages the
-     * head's deploy tree (deploy-tree write, pack, asset fan-out), fires the
-     * deployment `agent.deploy` frame carrying the workflow definition +
-     * source pin (the sidecar initializes the head repo and spawns the
-     * workflow-process child), then delivers the pack to the head. Returns
-     * the sidecar supervisor's principal public key. See `DeploySingleStepFn`.
-     */
-    deploySingleStepAtHead: DeploySingleStepFn;
-    /**
-     * Deploy a multi-step `WorkflowDefinition` through the workflow-deploy
-     * orchestrator's multi-step branch. This is the general workflow
-     * deploy entry point: it is not coupled to a single agent's
-     * credential/session model the way `launchSession` is. The
-     * orchestrator derives every per-step address
-     * from `deploymentId` + `deploymentDomain`, provisions each step's
-     * agent-state repo via the shared per-agent deploy phases, writes the
-     * workflow repo, and fires the deployment-level `agent.deploy` frame.
+     * Deploy a CODE-SOURCED workflow definition end to end: install + probe +
+     * gate + freeze (`approve-probed`), then deploy the frozen definition by
+     * source-ref. This is the general workflow deploy entry point the
+     * `POST /deployments` route drives; it never hydrates a live definition from a
+     * static `workflow.json`.
      *
-     * Persists one `workflow_deployment` projection row keyed by
-     * `deploymentId` so the deployment is listable per tenant; the
-     * RepoStore substrate has no by-kind listing API of its own.
+     * The service owns the source-read wiring (`repoStore` committed reads and
+     * asset pack fan-out) and the registry configuration, so the caller passes
+     * only the deploy intent: where the definition's bytes come from
+     * (`source`/`entry`/`pin`), the `workflow`-kind asset the definition projects
+     * over (`definitionAssetId`), and the shared harness config. The method
+     * dispatches on `source.kind`/`source.package.format` to build the install
+     * args, pins every top-level step's inference source under the frozen
+     * approval, and persists the deployment's anchor run.
      *
-     * Returns the supervisor's principal public key surfaced by the
-     * sidecar's `agent.deploy.ack`.
+     * Persists the deployment's anchor `workflow_run` (id = `anchorRunId`) via
+     * `deployCodeSourcedWorkflow`, so the deployment is listable per tenant.
+     * Returns the supervisor's principal public key from the sidecar deploy ack.
      */
-    deployWorkflowDefinition(params: DeployWorkflowDefinitionParams): Promise<DeployWorkflowDefinitionResult>;
+    deployWorkflowFromSource(params: DeployWorkflowFromSourceParams): Promise<DeployWorkflowDefinitionResult>;
     /**
      * Compose a signed RFC 2822 message from the user and deliver it to the
      * agent via the mail transport. Throws if the agent is unreachable.
@@ -90,49 +70,114 @@ export type SessionService = {
      */
     endSession(agentAddress: string, reason: string): Promise<void>;
 };
-export type DeployWorkflowDefinitionParams = {
-    /** Owning tenant; recorded on the projection row. */
+export type DeployWorkflowDefinitionResult = {
+    /** Echoes the deployment id recorded on the projection row. */
+    anchorRunId: string;
+    /** Deployment-level mail address the supervisor registers on the bus. */
+    deploymentAddress: string;
+    /** Supervisor principal public key from the sidecar's deploy ack. */
+    publicKey: string;
+};
+export type DeployWorkflowFromSourceParams = {
+    /** Owning tenant; recorded on the deployment's anchor run. */
     tenantId: string;
     /**
-     * Stable deployment identifier. The orchestrator concatenates it into
-     * every derived per-step address and the deployment-level address, and
-     * it is the `workflow_deployment` row's primary key. The caller owns
-     * its generation.
+     * Stable deployment identifier and anchor-run id. The deployment-level
+     * address derives from it; the caller owns its generation.
      */
-    deploymentId: string;
+    anchorRunId: string;
+    /** Mail domain the deployment's derived addresses live under. */
+    deploymentDomain: string;
     /**
-     * Mail domain the deployment's derived addresses live under. The
-     * orchestrator derives `ins_<deploymentId>-<stepId>@<deploymentDomain>`
-     * per step and `ins_<deploymentId>@<deploymentDomain>` for the
-     * deployment-level supervisor address.
+     * The deployment-level mail address, derived by the caller from `anchorRunId`
+     * + `deploymentDomain`. Re-derived and asserted coherent inside
+     * `deployCodeSourcedWorkflow`.
      */
-    deploymentDomain: string;
-    /** The hydrated workflow definition to deploy. */
-    definition: WorkflowDefinition;
+    agentAddress: string;
+    /** Where the definition's bytes come from at apply time. */
+    source: WorkflowDefinitionSource;
+    /** The `interchange.workflow` entry-module path the sidecar evaluates. */
+    entry: string;
+    /**
+     * A `name@range` spec for the definition package. REQUIRED for the `registry`
+     * and asset-`tarball` variants (the pin selects the member); omitted for the
+     * asset-`source` variant, whose member is selected by `package.packageName`.
+     */
+    pin?: string;
     /**
-     * The `workflow`-kind asset the definition was hydrated from. Recorded
-     * on the projection row so the listing surface can join back to the
-     * source asset.
+     * The `workflow`-kind asset the frozen definition projects a
+     * `workflow_definition` over. Distinct from a `source.kind === "asset"`
+     * source's `assetId`, which names where the bytes live.
      */
     definitionAssetId: string;
     /**
-     * Harness configuration shared across every step's launch. The
-     * orchestrator overrides `agentAddress`, `agentId`, and `systemPrompt`
-     * per step.
+     * Harness config shared across the deployment. Its `sources`/`defaultSource`
+     * are the operator-supplied inference chain; the method pins each top-level
+     * step to one approved source from it.
      */
     config: HarnessConfig;
-    /** Deploy-tree content shared across every step's launch. */
-    deployContent: DeployContent;
-    /** Tool-package pins to ship with every step's deploy. */
-    toolPackagePins?: readonly ToolPackagePin[];
 };
-export type DeployWorkflowDefinitionResult = {
-    /** Echoes the deployment id recorded on the projection row. */
-    deploymentId: string;
-    /** Deployment-level mail address the supervisor registers on the bus. */
-    deploymentAddress: string;
-    /** Supervisor principal public key from the sidecar's deploy ack. */
-    publicKey: string;
+/**
+ * Install/probe/gate/freeze inputs for a code-sourced workflow, DECOUPLED from
+ * deploy. The exclusive prepare path calls this on shared capacity at request
+ * time to freeze the approval, persists the frozen bundle, and deploys it to a
+ * dedicated allocation later with no re-probe.
+ */
+export type InstallAndApproveWorkflowSourceParams = {
+    /** Where the definition's bytes come from at probe time. */
+    source: WorkflowDefinitionSource;
+    /** The `interchange.workflow` entry-module path the sidecar evaluates. */
+    entry: string;
+    /**
+     * A `name@range` spec for the definition package. REQUIRED for the `registry`
+     * and asset-`tarball` variants; omitted for the asset-`source` variant.
+     */
+    pin?: string;
+    /** The `workflow`-kind asset the frozen definition projects a definition over. */
+    definitionAssetId: string;
+};
+/**
+ * Inputs to deploy a previously-frozen code-sourced approval bundle to a
+ * dedicated allocation. Mirrors `DeployPreparedWorkflowDefinitionParams` for the
+ * source-ref lineage: the anchor `workflow_run` row already exists from prepare
+ * time, so the deploy UPDATES it under the allocation-ownership lock rather than
+ * inserting a fresh one.
+ */
+export type DeployPreparedCodeSourcedWorkflowParams = {
+    /** Owning tenant; the definition's own tenant for credential resolution. */
+    tenantId: string;
+    /** The pre-inserted anchor run id, fixed at prepare time. */
+    anchorRunId: string;
+    /** Mail domain the deployment's derived addresses live under. */
+    deploymentDomain: string;
+    /** The deployment-level mail address; re-derived and asserted coherent. */
+    agentAddress: string;
+    /** Where the definition's bytes come from, rehydrated from the frozen bundle. */
+    source: WorkflowDefinitionSource;
+    /** The frozen approval bundle rehydrated from the launch spec. */
+    approved: InstallAndApproveResult;
+    /** Harness config carrying the re-resolved per-step inference chain. */
+    config: HarnessConfig;
+    /** The exact allocation generation to deploy onto. */
+    allocationTarget: AllocatedSidecarTarget;
+    /** Cipher for the definition's tenant-owned credential bindings, if any. */
+    credentialCipher?: CredentialCipher;
+};
+export type PreparedWorkflowDeployer = {
+    /**
+     * Install + probe + gate + freeze a code-sourced definition on shared
+     * capacity, returning the frozen bundle WITHOUT deploying it. The exclusive
+     * prepare path persists the bundle and deploys it later via
+     * `deployPreparedCodeSourcedWorkflow`.
+     */
+    installAndApproveWorkflowSource(params: InstallAndApproveWorkflowSourceParams): Promise<InstallAndApproveResult>;
+    /**
+     * Deploy a previously-frozen code-sourced approval bundle to a dedicated
+     * allocation, updating the pre-existing anchor run under the
+     * allocation-ownership lock. No re-probe: the frozen projection/hash/closure
+     * ride verbatim.
+     */
+    deployPreparedCodeSourcedWorkflow(params: DeployPreparedCodeSourcedWorkflowParams): Promise<DeployWorkflowDefinitionResult>;
 };
 export type UserMessageParams = {
     agentAddress: string;
@@ -149,6 +194,8 @@ export type UserMessageParams = {
 };
 export type SessionServiceDeps = {
     sidecarRouter: SidecarRouter;
+    /** Present when this Hub can route deploy phases to exclusive allocations. */
+    sidecarAllocationRouter?: SidecarAllocationRouter;
     agentRepoStore: AgentRepoStore;
     /**
      * Optional asset attachment integration. When set, the deploy flow
@@ -209,27 +256,161 @@ export type SessionServiceDeps = {
  * production multi-step callback does, rather than casting `unknown`.
  */
 export declare function bridgeOrchestratorDeployContent(content: OrchestratorDeployContent): DeployContent;
-/**
- * Wire the workflow-deploy orchestrator's `sendMultiStepDeploy`
- * dependency against `SidecarRouter.sendAgentDeploy`. The router
- * accepts an optional `workflow` projection on the deploy frame; the
- * sidecar's deploy router uses field presence to route the frame to
- * the workflow deploy path. The supervisor public key returned by the
- * sidecar's `agent.deploy.ack` is threaded back as the
- * `MultiStepDeployResult.publicKey`.
- *
- * Exported so the co-located caller-site test can assert that the
- * closure constructed in `launchSession` reaches the wire surface via
- * `sendAgentDeploy` with a `workflow` field structurally matching the
- * `AgentDeployFrame.workflow` schema.
- */
-export declare function sendMultiStepDeployFrame(args: {
+/** Fields the deploy frame carries onto `sendAgentDeploy`. */
+type DeployFrameCommonArgs = {
     sidecarRouter: SidecarRouter;
+    sidecarAllocationRouter?: SidecarAllocationRouter;
+    allocationTarget?: AllocatedSidecarTarget;
     agentAddress: string;
     config: HarnessConfig;
-    definition: WorkflowDefinition;
     sources: Record<string, InferenceSource[]>;
-}): Promise<{
+};
+/**
+ * For a code-sourced (npm) deploy the hub never holds the live
+ * `WorkflowDefinition` -- it lives only in the airlocked child. The gate/freeze
+ * layer hashed the inert projection; the deploy frame carries that hash and the
+ * source-ref pin, and the sidecar re-materializes and evaluates the pinned code
+ * from the pin, so no inline definition rides the frame. The content hash is
+ * owned by the gate, so this frame never recomputes it -- recomputing over a
+ * live wire lineage would diverge from the inert projection the child
+ * re-verifies against.
+ */
+export type SourceRefDeployFrameArgs = DeployFrameCommonArgs & {
+    lineage: "source-ref";
+    /**
+     * The gate-frozen wire hash of the approved projection -- stamped onto the
+     * frame VERBATIM. This arm does not recompute it: the freeze layer owns the
+     * content hash, and the child re-verifies its closure evaluation against this
+     * exact value.
+     */
+    approvedWireHash: string;
+    /**
+     * The source-ref pin: where the definition's bytes come from plus the frozen
+     * dependency closure the hub resolved for it. The two co-travel, so they are
+     * one required object on this arm (see `SourceRefPin`) -- the sidecar
+     * re-materializes the exact tree from the pin at apply time.
+     */
+    sourceRef: SourceRefPin;
+    /**
+     * Resolved credential material for the definition's credential bindings,
+     * delivered to the child on the frame. The hub resolves + decrypts here; the
+     * source-ref child decrypts nothing. The grant that AUTHORIZES a credential's
+     * use is minted per-run by run-grant materialization, not carried on this
+     * frame.
+     */
+    credentials?: CredentialDelivery;
+    /**
+     * The projection's inline onTrigger section bodies, each already in inert wire
+     * form with its per-step inference sources pinned and its own wire hash --
+     * built by `deployCodeSourcedWorkflow` from the frozen projection. The sidecar
+     * stages each body's `sources.json` (and re-verify hash). Absent when the
+     * projection has no inline onTrigger body.
+     */
+    referencedDefinitions?: readonly WorkflowProjectionWithSources[];
+    /**
+     * Source assets the pin's `kind:"asset"` closure entries read from, delivered
+     * inline on the frame so the sidecar checks them out into its durable
+     * per-deployment source store. Absent for a registry-sourced pin (its tarballs
+     * are fetched over HTTP).
+     */
+    assets?: readonly WorkflowSourceAssetMount[];
+};
+export type SendMultiStepDeployFrameArgs = SourceRefDeployFrameArgs;
+/**
+ * Emit the source-ref deploy frame onto `SidecarRouter.sendAgentDeploy`. The
+ * router accepts an optional `workflow` projection on the deploy frame; the
+ * sidecar's deploy router uses field presence to route the frame to the
+ * workflow deploy path, and returns the supervisor public key on the
+ * `agent.deploy.ack`.
+ *
+ * The gate/freeze layer already hashed the inert projection, so the frozen hash
+ * and the inert projection ride the frame verbatim -- this never recomputes the
+ * content hash. Recomputing over a live wire lineage would diverge from the
+ * inert projection the child re-verifies against.
+ *
+ * Exported so the co-located caller-site test can assert that the constructed
+ * closure reaches the wire surface via `sendAgentDeploy` with a `workflow`
+ * field structurally matching the `AgentDeployFrame.workflow` schema.
+ */
+export declare function sendMultiStepDeployFrame(args: SendMultiStepDeployFrameArgs): Promise<{
+    publicKey: string;
+}>;
+/**
+ * Arguments for `deployCodeSourcedWorkflow`. The `approved` bundle is the
+ * `installAndApproveWorkflowDefinition` output verbatim -- the frozen hash,
+ * inert projection, and closure travel together inside it so no caller can pair
+ * a hash with a mismatched projection or closure. The remaining fields are the
+ * operator/asset config the approve step never sees: the per-step inference
+ * `sources`, the deploy `config`, the target `agentAddress`, and the `source`
+ * ref that names where the definition's bytes are published.
+ */
+type DeployCodeSourcedCommonArgs = DeployFrameCommonArgs & {
+    approved: InstallAndApproveResult;
+    /**
+     * The hub DB handle, the definition's OWN tenant, the deployment's anchor run
+     * id, and the mail domain its run address lives under. REQUIRED: this function
+     * writes the deployment's anchor `workflow_run` row, and run-grant
+     * materialization keys off it. `tenantId` is the definition's own tenant
+     * (tenant-owned credential resolution walks up from it); do not pass a
+     * request/config tenant that may differ. `anchorRunId` is caller-supplied: the
+     * deployment mail address is frozen into the approved package bytes at
+     * authoring time, so the run id it derives from is fixed before this runs and
+     * cannot be minted here. `deploymentDomain` pairs with `anchorRunId` to
+     * re-derive the run address and assert it matches `agentAddress`, failing
+     * closed on an incoherent pair.
+     */
+    db: DB["db"];
+    tenantId: string;
+    anchorRunId: string;
+    deploymentDomain: string;
+    /**
+     * Credential cipher, REQUIRED only when the definition carries credential
+     * bindings (resolution fails closed without it); omit for a binding-free
+     * deployment.
+     */
+    credentialCipher?: CredentialCipher;
+    /**
+     * Present only for a prepared exclusive deploy: route the source-ref frame to
+     * this dedicated allocation instead of the shared router. `sidecarAllocationRouter`
+     * carries the allocation transport and is REQUIRED whenever `allocationTarget`
+     * is set. A shared deploy omits both.
+     */
+    allocationTarget?: AllocatedSidecarTarget;
+    sidecarAllocationRouter?: SidecarAllocationRouter;
+};
+/** Deploy a definition published to an npm registry: the sidecar fetches its
+ * tarballs over HTTP, so no source asset is delivered. */
+export type DeployCodeSourcedRegistryArgs = DeployCodeSourcedCommonArgs & {
+    source: WorkflowDefinitionRegistrySource;
+};
+/** Deploy a definition sourced from a hub `package-registry` asset: the caller
+ * mints `resolveAttachment` so this glue delivers the asset packs the sidecar
+ * checks out, without importing the asset service. */
+export type DeployCodeSourcedAssetArgs = DeployCodeSourcedCommonArgs & {
+    source: WorkflowDefinitionAssetSource;
+    resolveAttachment: ResolveAssetAttachmentFn;
+};
+export type DeployCodeSourcedWorkflowArgs = DeployCodeSourcedRegistryArgs | DeployCodeSourcedAssetArgs;
+/**
+ * The single public composition entrypoint for a SHARED code-sourced (npm)
+ * deploy: emit the source-ref frame, then INSERT the deployment's anchor
+ * `workflow_run` row -- the deployment's first-class record that owns its
+ * routing address and public key. Run-grant materialization keys off this row
+ * (address + live status), so WITHOUT it no per-run grants (tool, capability, OR
+ * credential) ever materialize for a source-ref deployment. Born "deployed"
+ * (live but pre-trigger): the first trigger's materialization flips it to
+ * "running" via `anchorWithPrincipal`'s guarded update, which a row born
+ * "running" would skip. Its `anchorRunId` equals its own id, so the anchor
+ * references itself. The deployer read grant is deferred to the production
+ * route, which carries the authenticated deployer principal; this stays a
+ * single insert with no grant row to pair atomically.
+ *
+ * The prepared exclusive path does NOT use this wrapper: its anchor row already
+ * exists from prepare time, so it wraps `emitSourceRefDeployFrame` with an
+ * UPDATE-under-allocation-lock instead of this INSERT.
+ */
+export declare function deployCodeSourcedWorkflow(args: DeployCodeSourcedWorkflowArgs): Promise<{
     publicKey: string;
 }>;
-export declare function createSessionService(deps: SessionServiceDeps): SessionService;
+export declare function createSessionService(deps: SessionServiceDeps): SessionService & PreparedWorkflowDeployer;
+export {};