@intx/hub-sessions 0.2.2 → 0.4.0

package/dist/hub-session-orchestrator.d.ts

@@ -1,20 +1,19 @@
 import type { DB } from "@intx/db";
-import type { AgentRepoStore } from "./agent-repo.js";
 import type { EventCollectorRegistry } from "./event-collector-registry.js";
 import type { SidecarEventEmitter } from "./ws/sidecar-events.js";
+import type { SenderDeploySettledOutcome } from "./ws/sidecar-handler.js";
 /** Subset of `SidecarRouter` the orchestrator drives outbound. The
  * narrow surface keeps tests honest and decouples the orchestrator
  * from the rest of the router API. */
 export type HubSessionRouterFacade = {
-    sendPack(agentAddress: string, pack: Uint8Array, ref: string, commitSha: string): Promise<void>;
     dispatchAgentEvent(agentAddress: string, event: unknown): void;
+    noteSenderDeploySettled(address: string, outcome: SenderDeploySettledOutcome): void;
 };
 export type HubSessionOrchestratorDeps = {
     events: SidecarEventEmitter;
     router: HubSessionRouterFacade;
     db: DB["db"];
     eventCollectors: EventCollectorRegistry;
-    agentRepoStore: AgentRepoStore;
 };
 export type HubSessionOrchestrator = {
     /** Unsubscribe all listeners. Tests use this between cases; the hub

package/dist/hub-session-orchestrator.js

@@ -11,15 +11,13 @@
 // with a small stub and an isolated emitter.
 import { eq } from "drizzle-orm";
 import { type } from "arktype";
-import { agentInstance, workflowDeployment } from "@intx/db/schema";
+import { workflowRun } from "@intx/db/schema";
 import { parseMailToEmail } from "@intx/mime";
 import { parseInferenceEvent } from "@intx/types/runtime";
 import { getLogger } from "@intx/log";
-import { isWorkflowDerivedAddress } from "@intx/workflow-deploy";
-import { findInstance, parseAgentId, requireInstance, } from "./hub-session-lookups.js";
 const log = getLogger(["hub", "orchestrator"]);
 export function createHubSessionOrchestrator(deps) {
-    const { events, router, db, eventCollectors, agentRepoStore } = deps;
+    const { events, router, db, eventCollectors } = deps;
     const unsubscribers = [];
     unsubscribers.push(events.on("agent.event", ({ agentAddress, event }) => {
         const validated = parseInferenceEvent(event);
@@ -45,61 +43,29 @@ export function createHubSessionOrchestrator(deps) {
             recipients: recipients.join(", "),
         });
     }));
-    unsubscribers.push(events.on("agent.deploy.ack", async ({ agentAddress, publicKey }) => {
-        // Workflow-derived addresses (the deployment-level
-        // `ins_<deploymentId>@<domain>` and the per-step
-        // `ins_<deploymentId>-<stepId>@<domain>`) have no agent_instance row;
-        // their public key lives on the workflow_deployment projection row,
-        // keyed by address. Persist it there so the reconnect ownership
-        // challenge can verify the deployment address. Only the
-        // deployment-level address has a row, so a stray per-step ack updates
-        // nothing. (This was previously a no-op, which is what left
-        // workflow-deployment addresses un-verifiable on reconnect.)
-        if (isWorkflowDerivedAddress(agentAddress)) {
-            await db
-                .update(workflowDeployment)
-                .set({ publicKey })
-                .where(eq(workflowDeployment.address, agentAddress));
+    unsubscribers.push(events.on("agent.deploy.ack", async (event) => {
+        const { agentAddress, publicKey, allocated } = event;
+        // Provisioned initialization publishes its key only after every deploy
+        // and asset pack succeeds under the allocation generation fence.
+        if (allocated !== undefined)
             return;
-        }
-        // A launched agent has an agent_instance row; a missing one is a bug
-        // to surface, not to drop silently.
-        const instance = await findInstance(db, agentAddress);
-        if (instance === undefined) {
-            throw new Error(`No active instance found for deploy ack on address "${agentAddress}"`);
-        }
+        // Every deploy address names a workflow run whose public key lives on its
+        // single self-anchored workflow_run row, keyed by address. Persist it
+        // there as the deployment's published identity. Reconnect routing is
+        // allocation-authenticated, so this projection is not connection
+        // authority. Only the deployment-level address owns a row, so a stray
+        // per-step ack updates nothing.
         await db
-            .update(agentInstance)
+            .update(workflowRun)
             .set({ publicKey })
-            .where(eq(agentInstance.id, instance.id));
-    }));
-    unsubscribers.push(events.on("agent.reconnected", async ({ agentAddress }) => {
-        const instance = await requireInstance(db, agentAddress);
-        if (!instance.sessionId) {
-            throw new Error(`Agent "${agentAddress}" reconnected but has no active session`);
-        }
-        const sessionId = instance.sessionId;
-        // A supervised deployment carries its grants and sources in the
-        // deploy pack and refreshes them over the supervisor's IPC
-        // credentials snapshot at spawn and recycle, so reconnect does not
-        // re-push them over the wire.
-        const now = new Date();
-        if (instance.status !== "running") {
-            await db
-                .update(agentInstance)
-                .set({ status: "running", updatedAt: now })
-                .where(eq(agentInstance.id, instance.id));
-        }
-        if (!eventCollectors.has(agentAddress)) {
-            eventCollectors.create(agentAddress, instance.tenantId, sessionId, instance.id);
-            log.info("Restored event collector for reconnected agent {agentAddress}", { agentAddress });
-        }
-    }));
-    unsubscribers.push(events.on("deploy.ref.stale", async ({ agentAddress }) => {
-        const agentId = parseAgentId(agentAddress);
-        const { pack, commitSha, ref } = await agentRepoStore.createDeployPack(agentId);
-        await router.sendPack(agentAddress, pack, ref, commitSha);
-        log.info("Re-deployed stale agent {agentAddress}", { agentAddress });
+            .where(eq(workflowRun.address, agentAddress));
+        // The key is now durable. Wake any mail the run parked while pre-ack so it
+        // is delivered with the sender key co-delivered, closing the window where
+        // a run sends before its key is recorded. The write above happens-before
+        // this settle, so a re-drive resolves the recorded key. The address is the
+        // run's own deploy address, byte-identical to the sender address its mail
+        // was sent under.
+        router.noteSenderDeploySettled(agentAddress, { recorded: publicKey });
     }));
     unsubscribers.push(events.on("mail.persisted", (row) => {
         const parsed = parseMailToEmail(row.raw, row.id);

package/dist/index.d.ts

@@ -1,18 +1,28 @@
 export { createAgentRepoStore, type AgentRepoStore, type DeployContent, } from "./agent-repo.js";
-export { createSessionService, SessionLaunchError, bridgeOrchestratorDeployContent, type SessionService, type DeployWorkflowDefinitionParams, type DeployWorkflowDefinitionResult, } from "./session-service.js";
+export { createSessionService, recoverSenderDeploy, SessionLaunchError, bridgeOrchestratorDeployContent, deployCodeSourcedWorkflow, type SessionService, type DeployWorkflowDefinitionResult, type DeployPreparedCodeSourcedWorkflowParams, type InstallAndApproveWorkflowSourceParams, type PreparedWorkflowDeployer, type DeployCodeSourcedWorkflowArgs, } from "./session-service.js";
+export { installAndApproveWorkflowDefinition, createDbFrozenApprovalWriter, type InstallAndApproveArgs, type InstallAndApproveResult, type ProbeGateResult, type ProbeApprovalPolicy, type ApproveProbedGrants, } from "./workflow-probe-gate.js";
+export { committedReadsToSourceTree } from "./committed-source-tree.js";
+export type { SourceTreeReads } from "./workflow-source-closure.js";
 export type { WorkflowDefinition } from "@intx/workflow/definition";
 export { createEventCollectorRegistry, type EventCollectorRegistry, } from "./event-collector-registry.js";
-export { createSidecarRouter, type SidecarRouter, type SidecarRouterConfig, type SidecarAuthIdentity, type SidecarAuthenticator, createSidecarTokenAuthenticator, type CreateSidecarTokenAuthenticatorDeps, type WsHandle, createSidecarEmitter, type SidecarEventEmitter, type SidecarEventMap, type SidecarEventType, type SidecarEventListener, type SidecarLookups, type SidecarMailPersistedPayload, type SidecarMailPersistedRow, } from "./ws/index.js";
-export { createHubSessionLookups, parseAgentId, type HubSessionLookupsDeps, } from "./hub-session-lookups.js";
+export { createSidecarRouter, type SidecarRouter, type SidecarRouterConfig, type SenderDeploySettledOutcome, type AllocatedSenderDeployAttempt, type SidecarAuthIdentity, type SidecarAuthenticator, type AllocatedSidecarTarget, type SidecarAllocationRouter, SidecarIdentityValidationError, createSidecarCredentialResolver, createSidecarTokenAuthenticator, type CreateSidecarTokenAuthenticatorDeps, type WsHandle, createSidecarEmitter, type SidecarEventEmitter, type SidecarEventMap, type SidecarEventType, type SidecarEventListener, type SidecarLookups, type SidecarMailPersistedPayload, type SidecarMailPersistedRow, type MailTriggeredRunGrantsResult, type WorkflowRunPackSource, } from "./ws/index.js";
+export { createHubSessionLookups, findRoutableById, parseAgentId, resolveRoutableAddress, resolveRunIdForSession, resolveRunSessionId, runRowToRoutableRecord, type HubSessionLookupsDeps, type RoutableEndpoint, type RoutableRecord, } from "./hub-session-lookups.js";
 export { createHubSessionOrchestrator, type HubSessionOrchestrator, type HubSessionOrchestratorDeps, type HubSessionRouterFacade, } from "./hub-session-orchestrator.js";
-export { pushSourceUpdates, pushSourceUpdatesSubtree } from "./credential-push.js";
+export { pushSourceUpdates, pushSourceUpdatesSubtree, pushCredentialRevoke, pushCredentialReconcile, } from "./credential-push.js";
+export { chooseFirstSidecarProvisioner, createSidecarPluginRegistry, createSidecarAllocationReconciler, type CreateSidecarPluginRegistryOpts, type DestroySidecarRequest, type DestroySidecarResult, type EnsureSidecarRequest, type EnsureSidecarResult, type SidecarCredentialIdentity, type SidecarCredentialResolver, type SidecarOperationFailure, type SidecarPluginRegistry, type SidecarProvisioner, type SidecarProvisionerChooser, type SidecarAllocationReconciler, type SidecarAllocationReconcilerDeps, type SidecarReconciliationContext, } from "./sidecar-allocation/index.js";
+export { ensureWorkflowDefinitionForAsset } from "./workflow-definition-ensure.js";
+export { workflowSourceAssetMountPath } from "./workflow-closure-resolution.js";
+export { createReconciliationScheduler, DEFAULT_SIDECAR_ALLOCATION_CONCURRENCY, type ReconciliationSchedulerOptions, } from "./reconciliation-scheduler.js";
+export { createWorkflowAllocationService, WorkflowProvisioningError, type PrepareProvisionedWorkflowDeploymentArgs, type PreparedProvisionedWorkflowDeployment, type WorkflowAllocationService, type WorkflowAllocationServiceDeps, } from "./workflow-allocation-service.js";
+export { createWorkflowDispatchService, type WorkflowDispatchAcknowledgement, type WorkflowDispatchService, type WorkflowDispatchServiceDeps, } from "./workflow-dispatch-service.js";
+export { listAcceptedWorkflowDispatches, listConsumedWorkflowDispatches, listReceivedWorkflowSignals, type AcceptedWorkflowDispatch, type ConsumedWorkflowDispatch, type ReceivedWorkflowSignal, } from "./workflow-dispatch-settlement.js";
 export { skillKindHandler, skillAuthorize, skillFrontmatterSchema, getSkillIndex, type SkillIndexEntry, type SkillFrontmatter, type SkillPrincipal, type SkillHubPrincipal, type SkillSidecarPrincipal, } from "./skill-kind.js";
 export { packageRegistryKindHandler, packageRegistryAuthorize, asTarballEntry, validateTarballPackageJSON, TARBALLS_PREFIX, TARBALL_FILENAME_PATTERN, REGISTRY_INDEX_PATH, WORKSPACE_BUILTINS_REGISTRY, } from "./package-registry-kind.js";
-export { workflowKindHandler, workflowAuthorize, workflowDefinitionEnvelopeSchema, WORKFLOW_JSON_PATH, CAPABILITY_DECLARATIONS_JSON_PATH, WORKFLOW_GITIGNORE_PATH, type WorkflowPrincipal, type WorkflowHubPrincipal, type WorkflowSidecarPrincipal, } from "./workflow-kind.js";
-export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, dequeueToProcessing, readProcessingEntry, markConsumed, readOwnedMessageIds, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, type ClaimCheckEnvelope, type ConsumedEnvelope, type EnqueueInboxArgs, type EnqueueInboxResult, type DequeueToProcessingResult, type ReadProcessingEntryResult, type MarkConsumedArgs, type MarkConsumedResult, type ReplayProcessingToInboxOpts, type ReplayProcessingToInboxResult, type WorkflowRunPrincipal, type WorkflowRunHubPrincipal, type WorkflowRunSidecarPrincipal, type WorkflowRunWorkflowProcessPrincipal, type WorkflowRunSupervisorPrincipal, } from "./workflow-run-kind.js";
-export { createAssetService, AssetServiceError, DEFAULT_ASSET_REF, type AssetService, type Asset, type AgentAsset, type AgentAssetWithAsset, type AccessMode, type CreateAssetParams, type PopulateAssetParams, type AttachAssetParams, type AssetServiceErrorReason, type ReadAssetBlobParams, type ListAssetBlobsParams, } from "./asset-service.js";
-export { buildAvailableSkillsStanza, type AvailableSkillEntry, } from "./available-skills-stanza.js";
+export { workflowKindHandler, workflowAuthorize, workflowDefinitionEnvelopeSchema, WORKFLOW_JSON_PATH, CAPABILITY_DECLARATIONS_JSON_PATH, type WorkflowPrincipal, type WorkflowHubPrincipal, type WorkflowSidecarPrincipal, } from "./workflow-kind.js";
+export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, StaleInboxEnqueueError, dequeueToProcessing, readProcessingEntry, markConsumed, classifyTerminalEvent, scanRunsForBoot, readCommittedWorkflowRunLifecycle, readWorkflowRunLifecycle, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_GRANTS_FILE, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, type ClaimCheckEnvelope, type ConsumedEnvelope, type EnqueueAlreadyPresentReason, type EnqueueInboxArgs, type EnqueueInboxOutcome, type EnqueueInboxResult, type DequeueToProcessingResult, type ReadProcessingEntryResult, type MarkConsumedArgs, type MarkConsumedResult, type WorkflowRunLifecycle, type ReplayProcessingToInboxOpts, type ReplayProcessingToInboxResult, type WorkflowRunPrincipal, type WorkflowRunHubPrincipal, type WorkflowRunSidecarPrincipal, type WorkflowRunWorkflowProcessPrincipal, type WorkflowRunSupervisorPrincipal, } from "./workflow-run-kind.js";
+export { restoreWorkflowRunToAllocation, WORKFLOW_RUN_RESTORE_REFS, } from "./workflow-run-restore.js";
+export { createAssetService, AssetServiceError, DEFAULT_ASSET_REF, type AssetService, type Asset, type CreateAssetParams, type PopulateAssetParams, type AssetServiceErrorReason, type ReadAssetBlobParams, type ListAssetBlobsParams, } from "./asset-service.js";
 export { createWorkflowRunReader, type WorkflowRunReader, type WorkflowRunEvent, } from "./workflow-run-reader.js";
 export { WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, encodeCombinedEventLog, } from "./workflow-run-event-log.js";
-export type { AuthorizeFn, CreateRepoStoreConfig, InitRepoOpts, KindHandler, NewlyTerminalRun, Principal, RefEntry, RepoAction, RepoId, RepoStore, SubscribeKindEntry, SubscribeKindOpts, ValidatePushResult, WriteResult, } from "./repo-store/index.js";
+export type { AuthorizeFn, CommittedReads, CommittedTreeEntry, CreateRepoStoreConfig, InitRepoOpts, KindHandler, NewlyTerminalRun, Principal, RefEntry, RepoAction, RepoId, RepoStore, SubscribeKindEntry, SubscribeKindOpts, ValidatePushResult, WriteResult, } from "./repo-store/index.js";
 export { createRepoStore, subscribeKind, UserPrincipal } from "./repo-store/index.js";

package/dist/index.js

@@ -1,16 +1,25 @@
 export { createAgentRepoStore, } from "./agent-repo.js";
-export { createSessionService, SessionLaunchError, bridgeOrchestratorDeployContent, } from "./session-service.js";
+export { createSessionService, recoverSenderDeploy, SessionLaunchError, bridgeOrchestratorDeployContent, deployCodeSourcedWorkflow, } from "./session-service.js";
+export { installAndApproveWorkflowDefinition, createDbFrozenApprovalWriter, } from "./workflow-probe-gate.js";
+export { committedReadsToSourceTree } from "./committed-source-tree.js";
 export { createEventCollectorRegistry, } from "./event-collector-registry.js";
-export { createSidecarRouter, createSidecarTokenAuthenticator, createSidecarEmitter, } from "./ws/index.js";
-export { createHubSessionLookups, parseAgentId, } from "./hub-session-lookups.js";
+export { createSidecarRouter, SidecarIdentityValidationError, createSidecarCredentialResolver, createSidecarTokenAuthenticator, createSidecarEmitter, } from "./ws/index.js";
+export { createHubSessionLookups, findRoutableById, parseAgentId, resolveRoutableAddress, resolveRunIdForSession, resolveRunSessionId, runRowToRoutableRecord, } from "./hub-session-lookups.js";
 export { createHubSessionOrchestrator, } from "./hub-session-orchestrator.js";
-export { pushSourceUpdates, pushSourceUpdatesSubtree } from "./credential-push.js";
+export { pushSourceUpdates, pushSourceUpdatesSubtree, pushCredentialRevoke, pushCredentialReconcile, } from "./credential-push.js";
+export { chooseFirstSidecarProvisioner, createSidecarPluginRegistry, createSidecarAllocationReconciler, } from "./sidecar-allocation/index.js";
+export { ensureWorkflowDefinitionForAsset } from "./workflow-definition-ensure.js";
+export { workflowSourceAssetMountPath } from "./workflow-closure-resolution.js";
+export { createReconciliationScheduler, DEFAULT_SIDECAR_ALLOCATION_CONCURRENCY, } from "./reconciliation-scheduler.js";
+export { createWorkflowAllocationService, WorkflowProvisioningError, } from "./workflow-allocation-service.js";
+export { createWorkflowDispatchService, } from "./workflow-dispatch-service.js";
+export { listAcceptedWorkflowDispatches, listConsumedWorkflowDispatches, listReceivedWorkflowSignals, } from "./workflow-dispatch-settlement.js";
 export { skillKindHandler, skillAuthorize, skillFrontmatterSchema, getSkillIndex, } from "./skill-kind.js";
 export { packageRegistryKindHandler, packageRegistryAuthorize, asTarballEntry, validateTarballPackageJSON, TARBALLS_PREFIX, TARBALL_FILENAME_PATTERN, REGISTRY_INDEX_PATH, WORKSPACE_BUILTINS_REGISTRY, } from "./package-registry-kind.js";
-export { workflowKindHandler, workflowAuthorize, workflowDefinitionEnvelopeSchema, WORKFLOW_JSON_PATH, CAPABILITY_DECLARATIONS_JSON_PATH, WORKFLOW_GITIGNORE_PATH, } from "./workflow-kind.js";
-export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, dequeueToProcessing, readProcessingEntry, markConsumed, readOwnedMessageIds, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, } from "./workflow-run-kind.js";
+export { workflowKindHandler, workflowAuthorize, workflowDefinitionEnvelopeSchema, WORKFLOW_JSON_PATH, CAPABILITY_DECLARATIONS_JSON_PATH, } from "./workflow-kind.js";
+export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, StaleInboxEnqueueError, dequeueToProcessing, readProcessingEntry, markConsumed, classifyTerminalEvent, scanRunsForBoot, readCommittedWorkflowRunLifecycle, readWorkflowRunLifecycle, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_GRANTS_FILE, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, } from "./workflow-run-kind.js";
+export { restoreWorkflowRunToAllocation, WORKFLOW_RUN_RESTORE_REFS, } from "./workflow-run-restore.js";
 export { createAssetService, AssetServiceError, DEFAULT_ASSET_REF, } from "./asset-service.js";
-export { buildAvailableSkillsStanza, } from "./available-skills-stanza.js";
 export { createWorkflowRunReader, } from "./workflow-run-reader.js";
 export { WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, encodeCombinedEventLog, } from "./workflow-run-event-log.js";
 export { createRepoStore, subscribeKind, UserPrincipal } from "./repo-store/index.js";

package/dist/reconciliation-scheduler.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_SIDECAR_ALLOCATION_CONCURRENCY = 8;
+export type ReconciliationSchedulerOptions = {
+    readonly name: string;
+    /** Claim and process at most one item; false means no due work was found. */
+    readonly reconcileNext: () => Promise<boolean>;
+    readonly concurrency?: number;
+    readonly intervalMs?: number;
+};
+/** Polls for work without waiting for other occupied slots to finish. */
+export declare function createReconciliationScheduler({ name, reconcileNext, concurrency, intervalMs, }: ReconciliationSchedulerOptions): {
+    start(): void;
+    stop(): void;
+    wake: () => void;
+};

package/dist/reconciliation-scheduler.js

@@ -0,0 +1,55 @@
+import { getLogger } from "@intx/log";
+const logger = getLogger(["hub", "reconciliation"]);
+export const DEFAULT_SIDECAR_ALLOCATION_CONCURRENCY = 8;
+/** Polls for work without waiting for other occupied slots to finish. */
+export function createReconciliationScheduler({ name, reconcileNext, concurrency = DEFAULT_SIDECAR_ALLOCATION_CONCURRENCY, intervalMs = 1_000, }) {
+    if (!Number.isSafeInteger(concurrency) || concurrency <= 0) {
+        throw new Error("Reconciliation concurrency must be a positive integer");
+    }
+    if (!Number.isSafeInteger(intervalMs) || intervalMs <= 0) {
+        throw new Error("Reconciliation interval must be a positive integer");
+    }
+    let stopped = true;
+    let active = 0;
+    let timer;
+    function finish(worked) {
+        active -= 1;
+        if (worked)
+            wake();
+    }
+    function wake() {
+        if (stopped)
+            return;
+        while (active < concurrency) {
+            active += 1;
+            void Promise.resolve()
+                .then(() => (stopped ? false : reconcileNext()))
+                .then(finish, (error) => {
+                logger.error `${name} reconciliation failed: ${error instanceof Error ? error.message : String(error)}`;
+                finish(false);
+            });
+        }
+    }
+    function schedule(delayMs) {
+        timer = setTimeout(() => {
+            if (stopped)
+                return;
+            wake();
+            schedule(intervalMs);
+        }, delayMs);
+        timer.unref?.();
+    }
+    return {
+        start() {
+            if (!stopped)
+                return;
+            stopped = false;
+            schedule(0);
+        },
+        stop() {
+            stopped = true;
+            clearTimeout(timer);
+        },
+        wake,
+    };
+}

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

@@ -1,4 +1,5 @@
-export type { AuthorizeFn, InitRepoOpts, KindHandler, NewlyTerminalRun, PriorDeltaReads, Principal, RefEntry, RepoAction, RepoId, RepoKind, RepoStore, RepoStoreSubscribeEvent, TreeContent, ValidatePushResult, WriteResult, WriteTreePreservingPrefixArgs, } from "./types.js";
+export type { AuthorizeFn, CommittedReads, CommittedTreeEntry, InitRepoOpts, KindHandler, NewlyTerminalRun, PriorDeltaReads, Principal, RefEntry, RepoAction, RepoId, RepoKind, RepoStore, RepoStoreSubscribeEvent, TreeContent, ValidatePushResult, WriteResult, WriteTreePreservingPrefixArgs, } from "./types.js";
 export { UserPrincipal } from "./types.js";
+export { authorizeUserPrincipal, type AuthorizeUserPrincipalArgs, } from "./user-principal-gate.js";
 export { createRepoStore, type CreateRepoStoreConfig } from "./store.js";
 export { subscribeKind, type SubscribeKindOpts, type SubscribeKindEntry, } from "./subscribe-kind.js";

package/dist/repo-store/index.js

@@ -1,3 +1,4 @@
 export { UserPrincipal } from "./types.js";
+export { authorizeUserPrincipal, } from "./user-principal-gate.js";
 export { createRepoStore } from "./store.js";
 export { subscribeKind, } from "./subscribe-kind.js";

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

@@ -1,4 +1,4 @@
-import { type CommitSigner, type GCPolicy } from "@intx/storage-isogit";
+import { type CommitSigner, type GCPolicy } from "@intx/storage-isogit/node";
 import type { AuthorizeFn, KindHandler, RepoId, RepoKind, RepoStore } from "./types.js";
 type SigningKey = {
     privateKey: Uint8Array;

package/dist/repo-store/store.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import git, {} from "isomorphic-git";
 import { createSSHSignature } from "@intx/crypto";
-import { initRepo as storageInitRepo, createDeployPack, receivePackObjects, collectReachableObjects, maybeGC, } from "@intx/storage-isogit";
+import { initRepo as storageInitRepo, createDeployPack, receivePackObjects, collectReachableObjects, maybeGC, } from "@intx/storage-isogit/node";
 import { hasCode } from "@intx/types";
 import { getLogger } from "@intx/log";
 import { SAFE_REPO_ID } from "./types.js";
@@ -638,6 +638,44 @@ export function createRepoStore(config) {
             out.set(e.path, e.oid);
         return out;
     }
+    // git tree-entry modes an admitted asset tree must not carry: a symlink can
+    // escape its directory when the tree is checked out, and a submodule gitlink
+    // is always a dangling reference (a pushed pack ships no submodule object).
+    const GIT_MODE_SYMLINK = "120000";
+    const GIT_MODE_SUBMODULE = "160000";
+    // Walk a commit's tree and return the first entry whose mode is disallowed
+    // (a symlink or a submodule), or null when the tree is clean. This mirrors
+    // the materialization backstop in `writeTreeToDisk`, but at the PUSH boundary
+    // so a directory-escaping symlink (or a dangling gitlink) is refused at
+    // admission rather than only caught later at checkout. It reads trees only,
+    // never blobs; `seen` deduplicates shared subtree oids across the commits of
+    // one pack so a subtree is walked once.
+    async function findDisallowedTreeMode(dir, treeOid, seen, prefix = "") {
+        if (seen.has(treeOid))
+            return null;
+        seen.add(treeOid);
+        const { tree } = await git.readTree({
+            fs,
+            dir,
+            cache: cacheFor(dir),
+            oid: treeOid,
+        });
+        for (const entry of tree) {
+            const entryPath = prefix === "" ? entry.path : `${prefix}/${entry.path}`;
+            if (entry.mode === GIT_MODE_SYMLINK) {
+                return { path: entryPath, kind: "symlink" };
+            }
+            if (entry.type === "commit" || entry.mode === GIT_MODE_SUBMODULE) {
+                return { path: entryPath, kind: "submodule" };
+            }
+            if (entry.type === "tree") {
+                const nested = await findDisallowedTreeMode(dir, entry.oid, seen, entryPath);
+                if (nested !== null)
+                    return nested;
+            }
+        }
+        return null;
+    }
     // Bound the set of paths a received-pack commit may have changed
     // relative to its parent, as repo-root-relative POSIX prefixes ending
     // in `/`. Git is content-addressed: a subtree whose object id is
@@ -1081,6 +1119,13 @@ export function createRepoStore(config) {
         const { priorReadBlob, priorListDir, priorListDirOids } = buildPriorTreeClosures(dir, parentCommitSha);
         const prospective = buildTreeReadClosures(dir, newRootTreeOid);
         const changedPathPrefixes = w.changedPathPrefixes;
+        // No disallowed-mode (symlink/submodule) gate here on purpose: the
+        // substrate mode gate lives on the pack-receive path. This write path
+        // cannot introduce a `120000`/`160000` entry -- `assembleTree` writes puts
+        // as `100644` and passes base-tree entries through unchanged, and no
+        // ingress ever admits such a mode into a base tree (the pack path is now
+        // gated; this path only writes `100644`). Adding a walk here would gate a
+        // tree that cannot carry those modes.
         const validation = await handler.validatePush({
             repoId,
             ref,
@@ -1325,6 +1370,7 @@ export function createRepoStore(config) {
                 existingCommitsCache.set(existingKey, existingCommits);
             }
             const newCommitsFromPack = [];
+            const newlyTerminalRuns = [];
             const oldSha = await receivePackObjects(dir, pack, ref, commitSha, transferId, expectedOldSha, 
             // A pack may carry more than one new commit (e.g. supervisor
             // bootstrap that batches enqueue + dequeue before the hub has
@@ -1340,6 +1386,9 @@ export function createRepoStore(config) {
             async () => {
                 const newCommits = await collectNewCommits(dir, commitSha, expectedOldSha, existingCommits);
                 newCommitsFromPack.push(...newCommits);
+                // Shared across the pack's commits so a subtree common to several is
+                // walked once by the disallowed-mode gate below.
+                const seenTreeOids = new Set();
                 for (const newCommit of newCommits) {
                     const { commit: parsed } = await git.readCommit({
                         fs,
@@ -1391,6 +1440,22 @@ export function createRepoStore(config) {
                     const { priorReadBlob, priorListDir, priorListDirOids } = buildPriorTreeClosures(dir, parentSha);
                     const { topLevelTreePaths, readBlob, listDir } = await buildCommitTreeClosures(dir, newCommit);
                     const changedPathPrefixes = await computeChangedPathPrefixes(dir, newCommit, parentSha);
+                    // Admission gate for EVERY kind, before the per-kind validatePush:
+                    // an asset tree carrying a symlink (which can escape its directory
+                    // at checkout) or a submodule (a dangling gitlink the pack cannot
+                    // reproduce) is refused here, so the ref never advances. No kind
+                    // legitimately pushes either; `writeTreeToDisk` rejects both at
+                    // materialization as the defense-in-depth backstop. Per-commit, so
+                    // an intermediate commit that adds a symlink a later commit deletes
+                    // is still caught.
+                    const disallowed = await findDisallowedTreeMode(dir, parsed.tree, seenTreeOids);
+                    if (disallowed !== null) {
+                        // The substrate owns the `path_violation:` prefix on the thrown
+                        // message, so the reason omits it (matching every handler reason).
+                        const reason = `${disallowed.kind} at ${disallowed.path} is not allowed in a pushed asset tree (commit ${newCommit})`;
+                        logger.debug `validatePush rejected ${repoId.kind}/${repoId.id} on ${ref} at commit ${newCommit}: ${reason}`;
+                        return { ok: false, reason };
+                    }
                     const result = await handler.validatePush({
                         repoId,
                         ref,
@@ -1407,6 +1472,9 @@ export function createRepoStore(config) {
                         logger.debug `validatePush rejected ${repoId.kind}/${repoId.id} on ${ref} at commit ${newCommit}: ${result.reason}`;
                         return { ok: false, reason: result.reason };
                     }
+                    if (result.newlyTerminalRuns !== undefined) {
+                        newlyTerminalRuns.push(...result.newlyTerminalRuns);
+                    }
                 }
                 return true;
             });
@@ -1420,6 +1488,7 @@ export function createRepoStore(config) {
             await handler.onRefUpdated({ repoId, ref, oldSha, newSha: commitSha });
             await emitRefUpdate(repoId, ref, oldSha, commitSha);
             await maybeRunGC(repoId);
+            return newlyTerminalRuns;
         });
     }
     async function createPack(principal, repoId, ref) {
@@ -1528,6 +1597,72 @@ export function createRepoStore(config) {
         gateAccess(principal, repoId, ref, "resolveRef");
         return resolveRefSha(repoDir(repoId), ref);
     }
+    // Build the committed-read closures pinned to a commit. Shared by the
+    // by-ref (`openCommittedReads`) and by-commit
+    // (`openCommittedReadsAtCommit`) entrypoints, which differ only in how
+    // they obtain and validate the commit SHA.
+    function committedReadsAt(dir, commitSha) {
+        const { readBlobByOid } = buildPriorTreeClosures(dir, commitSha);
+        const treeOid = async (relPath) => {
+            // "." and "" both name the root tree; resolveTreeEntry treats the
+            // empty string as the root, so normalize "." to it.
+            const normalized = relPath === "." ? "" : relPath;
+            return resolveTreeEntry(dir, commitSha, normalized, "tree");
+        };
+        const listDir = async (relPath) => {
+            const oid = await treeOid(relPath);
+            if (oid === null)
+                return [];
+            const { tree } = await git.readTree({
+                fs,
+                dir,
+                cache: cacheFor(dir),
+                oid,
+            });
+            return tree.map((e) => ({ name: e.path, oid: e.oid, type: e.type }));
+        };
+        return { listDir, readBlobByOid, treeOid };
+    }
+    async function repoHasGitDir(dir) {
+        return fs.promises
+            .stat(path.join(dir, ".git"))
+            .then(() => true)
+            .catch(() => false);
+    }
+    async function openCommittedReads(principal, repoId, ref) {
+        gateAccess(principal, repoId, ref, "resolveRef");
+        const dir = repoDir(repoId);
+        if (!(await repoHasGitDir(dir)))
+            return null;
+        const commitSha = await resolveRefSha(dir, ref);
+        if (commitSha === null)
+            return null;
+        return committedReadsAt(dir, commitSha);
+    }
+    async function openCommittedReadsAtCommit(principal, repoId, commitSha) {
+        // No single ref to gate on; use the same `"*"`/`resolveRef` bulk-read
+        // gate that `listRefs` and `resolveHead` use.
+        gateAccess(principal, repoId, "*", "resolveRef");
+        if (!/^[0-9a-f]{40}$/.test(commitSha)) {
+            throw new Error(`commit_sha_invalid: ${commitSha}`);
+        }
+        const dir = repoDir(repoId);
+        if (!(await repoHasGitDir(dir)))
+            return null;
+        // Confirm the commit object is present so a pruned commit reads as a
+        // clean `null` rather than a lazy throw on the first tree walk.
+        const present = await git
+            .readCommit({ fs, dir, cache: cacheFor(dir), oid: commitSha })
+            .then(() => true)
+            .catch((err) => {
+            if (hasCode(err) && err.code === "NotFoundError")
+                return false;
+            throw err;
+        });
+        if (!present)
+            return null;
+        return committedReadsAt(dir, commitSha);
+    }
     function subscribe(principal, repoId, ref, opts) {
         gateAccess(principal, repoId, ref, "resolveRef");
         const bufferLimit = opts.bufferLimit ?? DEFAULT_SUBSCRIBE_BUFFER_LIMIT;
@@ -1687,6 +1822,8 @@ export function createRepoStore(config) {
         listRefs,
         resolveHead,
         getRepoDir,
+        openCommittedReads,
+        openCommittedReadsAtCommit,
         subscribe,
     };
 }

package/dist/repo-store/subscribe-kind.d.ts

@@ -40,9 +40,12 @@ export type SubscribeKindEntry<T> = {
  * kinds filter against the inner `type` discriminator, and yields one
  * `{ seq, event }` entry per matching blob.
  *
- * The path layout is owned here, not in the substrate: the substrate
- * `subscribe` is a generic ref-tail primitive and knows nothing about
- * workflow-runs.
+ * The path-layout vocabulary (the `runs/`/`events/` prefixes and the
+ * `<seq>.json` filename shape) lives in the workflow-run kind handler,
+ * which is the authority for what may land under this prefix; this
+ * helper imports it rather than re-encoding it. The substrate
+ * `subscribe` it wraps is a generic ref-tail primitive and knows
+ * nothing about workflow-runs.
  *
  * Diff scope: the helper enumerates event blobs present in the new
  * commit but absent from the old commit. A commit that does not add