@intx/hub-sessions 0.1.2 → 0.3.0

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

@@ -0,0 +1,25 @@
+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";
+/** 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;
+};
+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
+     * application doesn't need to dispose because the orchestrator's
+     * lifetime matches the process. */
+    dispose(): void;
+};
+export declare function createHubSessionOrchestrator(deps: HubSessionOrchestratorDeps): HubSessionOrchestrator;

package/dist/hub-session-orchestrator.js

@@ -0,0 +1,87 @@
+// Hub-side orchestrator for the sidecar event emitter.
+//
+// Subscribes to the sidecar router's events and runs the host-side
+// reactions: dispatching inference events to the event collector,
+// restoring the event collector on reconnect, re-deploying stale
+// agents, and forwarding mail.delivered notifications back to
+// subscribers.
+//
+// The orchestrator depends on a narrow `HubSessionRouterFacade` rather
+// than the full SidecarRouter, so tests can drive subscriber behavior
+// with a small stub and an isolated emitter.
+import { eq } from "drizzle-orm";
+import { type } from "arktype";
+import { workflowRun } from "@intx/db/schema";
+import { parseMailToEmail } from "@intx/mime";
+import { parseInferenceEvent } from "@intx/types/runtime";
+import { getLogger } from "@intx/log";
+import { parseAgentId } from "./hub-session-lookups.js";
+const log = getLogger(["hub", "orchestrator"]);
+export function createHubSessionOrchestrator(deps) {
+    const { events, router, db, eventCollectors, agentRepoStore } = deps;
+    const unsubscribers = [];
+    unsubscribers.push(events.on("agent.event", ({ agentAddress, event }) => {
+        const validated = parseInferenceEvent(event);
+        if (validated instanceof type.errors) {
+            log.warn("Received invalid agent event for {agentAddress}: {summary}", {
+                agentAddress,
+                summary: validated.summary,
+            });
+            return;
+        }
+        eventCollectors.dispatch(agentAddress, validated);
+    }));
+    unsubscribers.push(events.on("sidecar.disconnect", ({ ownedAddresses }) => {
+        for (const addr of ownedAddresses) {
+            eventCollectors.abandon(addr);
+        }
+    }));
+    unsubscribers.push(events.on("mail.outbound.undelivered", ({ recipients }) => {
+        // The hub has no external mail transport today. Anything that
+        // could not be delivered locally or queued for a disconnected
+        // agent is dropped; log so operators can see it.
+        log.warn("Dropping mail with no local recipient: {recipients}", {
+            recipients: recipients.join(", "),
+        });
+    }));
+    unsubscribers.push(events.on("agent.deploy.ack", async (event) => {
+        const { agentAddress, publicKey, allocated } = event;
+        // Exclusive initialization publishes its key only after every deploy
+        // and asset pack succeeds under the allocation generation fence.
+        if (allocated !== undefined)
+            return;
+        // 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 so the reconnect ownership challenge can verify the address off
+        // the same row `lookupPublicKey` reads. Only the deployment-level address
+        // owns a row, so a stray per-step ack updates nothing.
+        await db
+            .update(workflowRun)
+            .set({ publicKey })
+            .where(eq(workflowRun.address, 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 });
+    }));
+    unsubscribers.push(events.on("mail.persisted", (row) => {
+        const parsed = parseMailToEmail(row.raw, row.id);
+        router.dispatchAgentEvent(row.address, {
+            type: "mail.delivered",
+            data: {
+                ...parsed,
+                id: row.id,
+                direction: row.direction,
+                receivedAt: row.createdAt.toISOString(),
+            },
+        });
+    }));
+    return {
+        dispose() {
+            for (const off of unsubscribers)
+                off();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export { createAgentRepoStore, type AgentRepoStore, type DeployContent, } from "./agent-repo.js";
+export { createSessionService, SessionLaunchError, bridgeOrchestratorDeployContent, deployCodeSourcedWorkflow, type SessionService, type DeployWorkflowDefinitionResult, type DeployWorkflowFromSourceParams, 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, type AllocatedSidecarTarget, type SidecarAllocationRouter, 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 { createSidecarPluginRegistry, createSidecarAllocationReconciler, resolveEffectiveSidecarPlacement, type CreateSidecarPluginRegistryOpts, type DestroySidecarRequest, type DestroySidecarResult, type EnsureSidecarRequest, type EnsureSidecarResult, type ResolveEffectiveSidecarPlacementOpts, type SidecarCredentialIdentity, type SidecarCredentialResolver, type SidecarOperationFailure, type SidecarPluginRegistry, type SidecarProvisioner, type SidecarAllocationReconciler, type SidecarAllocationReconcilerDeps, } from "./sidecar-allocation/index.js";
+export { ensureWorkflowDefinitionForAsset } from "./workflow-definition-ensure.js";
+export { workflowSourceAssetMountPath } from "./workflow-closure-resolution.js";
+export { createWorkflowAllocationService, ExclusiveWorkflowPlacementError, resolveWorkflowSidecarPlacement, type PrepareExclusiveWorkflowDeploymentArgs, type PreparedExclusiveWorkflowDeployment, 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, type WorkflowPrincipal, type WorkflowHubPrincipal, type WorkflowSidecarPrincipal, } from "./workflow-kind.js";
+export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, StaleInboxEnqueueError, dequeueToProcessing, readProcessingEntry, markConsumed, readOwnedMessageIds, 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, 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

@@ -0,0 +1,24 @@
+export { createAgentRepoStore, } from "./agent-repo.js";
+export { createSessionService, 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, 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 { createSidecarPluginRegistry, createSidecarAllocationReconciler, resolveEffectiveSidecarPlacement, } from "./sidecar-allocation/index.js";
+export { ensureWorkflowDefinitionForAsset } from "./workflow-definition-ensure.js";
+export { workflowSourceAssetMountPath } from "./workflow-closure-resolution.js";
+export { createWorkflowAllocationService, ExclusiveWorkflowPlacementError, resolveWorkflowSidecarPlacement, } 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, } from "./workflow-kind.js";
+export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, StaleInboxEnqueueError, dequeueToProcessing, readProcessingEntry, markConsumed, readOwnedMessageIds, 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 { 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/package-registry-kind.d.ts

@@ -0,0 +1,70 @@
+import type { PackageJSON } from "@intx/types/package-json";
+import { type AuthorizeFn, type KindHandler } from "./repo-store/index.js";
+export declare const TARBALLS_PREFIX = "tarballs/";
+export declare const REGISTRY_INDEX_PATH = "package-registry.json";
+/**
+ * Canonical asset name for the workspace's bundled package-registry —
+ * the in-tree `@intx/tools-*` packages live in an asset of this name
+ * under the workspace's root tenant. The hub's scope-routing config
+ * maps `@intx` to this registry, the seed script ensures the asset
+ * row exists, and the publish-tool-packages CLI defaults its target
+ * registry to this name. The constant lives at one site so a rename
+ * does not have to chase three independent string literals.
+ *
+ * Callers:
+ *   - `bin/dev.ts` — orchestrator default for the registry the dev
+ *     stack publishes the built-ins into.
+ *   - `bin/seed.ts` — seeder that pins the workspace-builtins into
+ *     the registry asset at boot.
+ *   - `bin/publish-tool-packages.ts` — CLI default for the
+ *     `--registry` flag.
+ *
+ * No test asserts that the seed's pinned built-ins actually land
+ * under this exact name; a mismatch between the constant and a
+ * caller would surface at apply time as a `tarball.missing`
+ * structured failure, not as a build error.
+ */
+export declare const WORKSPACE_BUILTINS_REGISTRY = "workspace-builtins";
+/**
+ * Filename rule for tarballs in the repo tree. Filenames must end in
+ * `.tgz`, start with an alphanumeric / underscore / scope-marker
+ * character, and otherwise contain only filename-safe characters. The
+ * leading-character constraint forbids hidden-style names like
+ * `..tgz` or `.hidden.tgz` that the filesystem treats as dotfiles —
+ * those would be invisible to a `readdir` shell expansion and split
+ * the resolver's view of the registry tree from the operator's. The
+ * same rule is enforced at the REST upload boundary so a push and a
+ * PUT cannot produce diverging contents.
+ */
+export declare const TARBALL_FILENAME_PATTERN: RegExp;
+/**
+ * Validates that `path` belongs to a tarball entry shape
+ * `tarballs/<filename>.tgz`. Returns the bare filename when valid,
+ * `null` otherwise.
+ */
+export declare function asTarballEntry(path: string): string | null;
+type TarballValidationOutcome = {
+    ok: true;
+    pkg: PackageJSON;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Open an npm-style tarball, find the top-level `package.json` entry,
+ * parse and validate it. Returns the typed descriptor on success; a
+ * structured reason otherwise. The shape validation lives inside
+ * `extractTarballPackageJSON`; this wrapper only translates the
+ * outcome into the substrate's `ValidatePushResult`-shaped reason
+ * strings.
+ */
+export declare function validateTarballPackageJSON(filename: string, bytes: Uint8Array): Promise<TarballValidationOutcome>;
+export declare const packageRegistryKindHandler: KindHandler;
+/**
+ * Authorize policy for package-registry repos. Sidecars never write
+ * to package-registry repos (they consume contents through the
+ * in-process read API, not the smart-HTTP layer); only the hub and
+ * authenticated users with the right grant may push.
+ */
+export declare const packageRegistryAuthorize: AuthorizeFn;
+export {};

package/dist/package-registry-kind.js

@@ -0,0 +1,260 @@
+// KindHandler for the `package-registry` asset kind.
+//
+// A package-registry asset is a git repo whose top-level tree holds:
+//
+//   - `tarballs/<filename>.tgz` — one or more npm-style tarballs. Each
+//     tarball is opened during validation; its inner `package.json`
+//     must validate against `PackageJSON`. Anything else under
+//     `tarballs/` is rejected.
+//   - `package-registry.json` (optional) — a hub-authored index. The
+//     substrate does not enforce its shape today; the resolver layer
+//     consumes it when present.
+//   - `.gitignore` — supplied by the asset routes' genesis init body.
+//
+// Any top-level entry outside this set fails the push.
+import { getLogger } from "@intx/log";
+import { extractTarballPackageJSON } from "@intx/tool-packaging";
+import {} from "./repo-store/index.js";
+const logger = getLogger(["hub-sessions", "package-registry-kind"]);
+export const TARBALLS_PREFIX = "tarballs/";
+export const REGISTRY_INDEX_PATH = "package-registry.json";
+/**
+ * Canonical asset name for the workspace's bundled package-registry —
+ * the in-tree `@intx/tools-*` packages live in an asset of this name
+ * under the workspace's root tenant. The hub's scope-routing config
+ * maps `@intx` to this registry, the seed script ensures the asset
+ * row exists, and the publish-tool-packages CLI defaults its target
+ * registry to this name. The constant lives at one site so a rename
+ * does not have to chase three independent string literals.
+ *
+ * Callers:
+ *   - `bin/dev.ts` — orchestrator default for the registry the dev
+ *     stack publishes the built-ins into.
+ *   - `bin/seed.ts` — seeder that pins the workspace-builtins into
+ *     the registry asset at boot.
+ *   - `bin/publish-tool-packages.ts` — CLI default for the
+ *     `--registry` flag.
+ *
+ * No test asserts that the seed's pinned built-ins actually land
+ * under this exact name; a mismatch between the constant and a
+ * caller would surface at apply time as a `tarball.missing`
+ * structured failure, not as a build error.
+ */
+export const WORKSPACE_BUILTINS_REGISTRY = "workspace-builtins";
+/**
+ * Filename rule for tarballs in the repo tree. Filenames must end in
+ * `.tgz`, start with an alphanumeric / underscore / scope-marker
+ * character, and otherwise contain only filename-safe characters. The
+ * leading-character constraint forbids hidden-style names like
+ * `..tgz` or `.hidden.tgz` that the filesystem treats as dotfiles —
+ * those would be invisible to a `readdir` shell expansion and split
+ * the resolver's view of the registry tree from the operator's. The
+ * same rule is enforced at the REST upload boundary so a push and a
+ * PUT cannot produce diverging contents.
+ */
+export const TARBALL_FILENAME_PATTERN = /^[A-Za-z0-9_@+][A-Za-z0-9_.@+-]*\.tgz$/;
+/**
+ * Validates that `path` belongs to a tarball entry shape
+ * `tarballs/<filename>.tgz`. Returns the bare filename when valid,
+ * `null` otherwise.
+ */
+export function asTarballEntry(path) {
+    if (!path.startsWith(TARBALLS_PREFIX))
+        return null;
+    const filename = path.slice(TARBALLS_PREFIX.length);
+    if (filename.length === 0)
+        return null;
+    if (filename.includes("/"))
+        return null;
+    if (!TARBALL_FILENAME_PATTERN.test(filename))
+        return null;
+    return filename;
+}
+/**
+ * Open an npm-style tarball, find the top-level `package.json` entry,
+ * parse and validate it. Returns the typed descriptor on success; a
+ * structured reason otherwise. The shape validation lives inside
+ * `extractTarballPackageJSON`; this wrapper only translates the
+ * outcome into the substrate's `ValidatePushResult`-shaped reason
+ * strings.
+ */
+export async function validateTarballPackageJSON(filename, bytes) {
+    const outcome = await extractTarballPackageJSON(bytes);
+    if (outcome.kind === "missing-entry") {
+        return {
+            ok: false,
+            reason: `tarball ${filename} has no top-level package.json entry`,
+        };
+    }
+    if (outcome.kind === "multiple-entries") {
+        // The hub validates the first top-level package.json the tar walk
+        // emits, but the sidecar's `tar.extract({ strip: 1 })` overwrites
+        // on every subsequent path with the same stripped name and ends up
+        // loading the LAST entry. A tarball carrying more than one
+        // `<seg>/package.json` therefore would have its hub-side validation
+        // and sidecar-side runtime read different descriptors — exactly
+        // the kind of TOCTOU gap a single signed integrity hash cannot
+        // close. Reject the upload at the validation boundary.
+        return {
+            ok: false,
+            reason: `tarball ${filename} contains multiple top-level package.json entries (${outcome.paths
+                .map((p) => JSON.stringify(p))
+                .join(", ")}); npm tarballs must hold exactly one top-level package directory`,
+        };
+    }
+    if (outcome.kind === "parse-error") {
+        return {
+            ok: false,
+            reason: `tarball ${filename} failed to parse: ${outcome.message}`,
+        };
+    }
+    if (outcome.kind === "json-error") {
+        return {
+            ok: false,
+            reason: `tarball ${filename} package.json is not valid JSON: ${outcome.message}`,
+        };
+    }
+    if (outcome.kind === "shape-invalid") {
+        return {
+            ok: false,
+            reason: `tarball ${filename} package.json failed validation: ${outcome.message}`,
+        };
+    }
+    return { ok: true, pkg: outcome.parsed };
+}
+export const packageRegistryKindHandler = {
+    kind: "package-registry",
+    directoryPrefix: "assets/package-registry",
+    async validatePush({ repoId, ref, topLevelTreePaths, readBlob, listDir, }) {
+        // The substrate hands us every top-level tree entry — both
+        // directories and files — from both the receivePack and writeTree
+        // adapters. The allowed set is `tarballs`, `.gitignore`, and
+        // `package-registry.json`.
+        for (const entry of topLevelTreePaths) {
+            if (entry === "tarballs" ||
+                entry === ".gitignore" ||
+                entry === REGISTRY_INDEX_PATH) {
+                continue;
+            }
+            return {
+                ok: false,
+                reason: `unexpected top-level entry ${JSON.stringify(entry)}; allowed: "tarballs", "${REGISTRY_INDEX_PATH}", ".gitignore"`,
+            };
+        }
+        // Enumerate every entry under `tarballs/`, validate the filename
+        // shape, then open each tarball and validate its package.json.
+        // Gate on `topLevelTreePaths` so a tree without a `tarballs/`
+        // subtree (the genesis commit, or any push that simply does not
+        // include tarballs yet) skips the enumeration: the substrate's
+        // `listDir` returns `[]` for an absent path, which is
+        // indistinguishable from a present-but-empty `tarballs/` subtree.
+        // "Is the subtree there at all" is therefore answered at the handler
+        // from the top-level enumeration the substrate already supplies, not
+        // from a probe call. With `tarballs` confirmed present, any throw
+        // from the `listDir` below is a real fault (EACCES, EIO, malformed
+        // tree, transient transport), so it is surfaced rather than treated
+        // as "no tarballs."
+        let tarballChildren;
+        if (!topLevelTreePaths.includes("tarballs")) {
+            tarballChildren = [];
+        }
+        else {
+            try {
+                tarballChildren = await listDir("tarballs");
+            }
+            catch (err) {
+                // The top-level enumeration already told us `tarballs` is
+                // present, so any failure here is a real listDir fault
+                // (EACCES, EIO, malformed-tree, transient transport) — not
+                // "the subtree is absent." Surface it as a push rejection
+                // rather than collapsing it into "no tarballs to validate,"
+                // which would silently let a push through whose tarballs
+                // subtree could not be enumerated.
+                return {
+                    ok: false,
+                    reason: `failed to list tarballs subtree: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        }
+        // Two tarballs publishing the same `${name}@${version}` make the
+        // resolver's AssetRegistrySource overwrite by fs.readdir order —
+        // an undefined-behaviour outcome across filesystems. Reject the
+        // collision at the substrate boundary so the registry asset's
+        // closure is unambiguous regardless of how the loader walks it.
+        const publishedNameVersions = new Set();
+        for (const child of tarballChildren) {
+            const repoPath = `${TARBALLS_PREFIX}${child}`;
+            const filename = asTarballEntry(repoPath);
+            if (filename === null) {
+                return {
+                    ok: false,
+                    reason: `tarball path ${JSON.stringify(repoPath)} must match tarballs/<filename>.tgz with filename-safe characters and a .tgz extension`,
+                };
+            }
+            let bytes;
+            try {
+                bytes = await readBlob(repoPath);
+            }
+            catch (cause) {
+                return {
+                    ok: false,
+                    reason: `tarball ${repoPath} could not be read from the tree: ${cause instanceof Error ? cause.message : String(cause)}`,
+                };
+            }
+            const outcome = await validateTarballPackageJSON(filename, bytes);
+            if (!outcome.ok) {
+                logger.debug `package-registry validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${outcome.reason}`;
+                return { ok: false, reason: outcome.reason };
+            }
+            const key = `${outcome.pkg.name}@${outcome.pkg.version}`;
+            if (publishedNameVersions.has(key)) {
+                return {
+                    ok: false,
+                    reason: `package-registry contains multiple tarballs publishing ${key}; each name@version pair must appear in exactly one tarball`,
+                };
+            }
+            publishedNameVersions.add(key);
+        }
+        return { ok: true };
+    },
+    onRefUpdated() {
+        // No cached index today. The resolver reads the asset's contents
+        // through `readAssetBlob`/`listAssetBlobs` at session time.
+    },
+};
+/**
+ * Authorize policy for package-registry repos. Sidecars never write
+ * to package-registry repos (they consume contents through the
+ * in-process read API, not the smart-HTTP layer); only the hub and
+ * authenticated users with the right grant may push.
+ */
+export const packageRegistryAuthorize = (principal, repoId, _ref, action) => {
+    if (repoId.kind !== "package-registry") {
+        return {
+            allowed: false,
+            reason: `package-registry authorize received non-package-registry repo ${repoId.kind}/${repoId.id}`,
+        };
+    }
+    if (principal.kind === "hub") {
+        return { allowed: true };
+    }
+    if (principal.kind === "sidecar") {
+        return {
+            allowed: false,
+            reason: `sidecars do not access package-registry assets via the substrate; action=${action}`,
+        };
+    }
+    // The smart-HTTP route layer treats package-registry repos as
+    // user-write-denied by design: tarball writes are constrained to the
+    // shape the kind handler validates (`tarballs/<filename>.tgz` plus a
+    // hub-authored index), and the REST PUT/DELETE endpoints on the
+    // asset routes (`PUT /api/tenants/:tid/assets/:assetId/tarballs/:filename`
+    // and the matching DELETE) are the supported path for users who
+    // need to publish a tarball. Smart-HTTP would let a user push
+    // arbitrary tree shapes that the kind handler would then have to
+    // reject after the fact; the REST surface validates ahead of write.
+    return {
+        allowed: false,
+        reason: `principal kind ${principal.kind} cannot push to package-registry over smart-HTTP; use the REST tarball endpoints (PUT/DELETE /api/tenants/:tid/assets/:assetId/tarballs/:filename)`,
+    };
+};

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

@@ -0,0 +1,4 @@
+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 { createRepoStore, type CreateRepoStoreConfig } from "./store.js";
+export { subscribeKind, type SubscribeKindOpts, type SubscribeKindEntry, } from "./subscribe-kind.js";

package/dist/repo-store/index.js

@@ -0,0 +1,3 @@
+export { UserPrincipal } from "./types.js";
+export { createRepoStore } from "./store.js";
+export { subscribeKind, } from "./subscribe-kind.js";

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

@@ -0,0 +1,41 @@
+import { type CommitSigner, type GCPolicy } from "@intx/storage-isogit/node";
+import type { AuthorizeFn, KindHandler, RepoId, RepoKind, RepoStore } from "./types.js";
+type SigningKey = {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+export type CreateRepoStoreConfig = {
+    dataDir: string;
+    signingKey: SigningKey;
+    /**
+     * Handler map keyed by repo kind. The substrate throws at request
+     * time when a kind has no registered handler, so callers may omit
+     * kinds they do not service (e.g. a per-asset-kind store that only
+     * registers `skill`).
+     */
+    handlers: Partial<Record<RepoKind, KindHandler>>;
+    authorize: AuthorizeFn;
+    /**
+     * Optional per-repo signing callback. When supplied and the callback
+     * returns a `CommitSigner` for the given `repoId`, the substrate
+     * passes that signer to `initRepo` so the genesis commit is authored
+     * as `interchange-hub` and signed. When the callback returns
+     * `undefined`, or the field is omitted entirely, the substrate falls
+     * back to the unsigned harness-authored genesis.
+     */
+    signingCallback?: (repoId: RepoId) => CommitSigner | undefined;
+    /**
+     * Optional write-path garbage-collection policy. When supplied, after
+     * every successful write under the repo lock the substrate applies the
+     * shared reclaim policy to repos whose kind is in `kinds`. Omitted
+     * entirely, the substrate never reclaims and never warns. The `kinds`
+     * allowlist keeps the policy scoped to the kinds the caller intends
+     * (e.g. `agent-state`) rather than every kind the store happens to
+     * service.
+     */
+    gc?: GCPolicy & {
+        kinds: readonly RepoKind[];
+    };
+};
+export declare function createRepoStore(config: CreateRepoStoreConfig): RepoStore;
+export {};