@intx/hub-sessions 0.1.2 → 0.2.2

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

@@ -0,0 +1,17 @@
+import type { DB } from "@intx/db";
+import type { AgentRepoStore } from "./agent-repo.js";
+import type { SidecarLookups } from "./ws/sidecar-events.js";
+export type HubSessionLookupsDeps = {
+    db: DB["db"];
+    agentRepoStore: AgentRepoStore;
+};
+export declare function createHubSessionLookups(deps: HubSessionLookupsDeps): Required<SidecarLookups>;
+/**
+ * Extract the instance id from an `<instanceId>@<domain>` agent address.
+ * Throws on any input the `@intx/types`-owned `parseAgentAddress`
+ * rejects: missing or leading `@`, empty domain, or an instance id
+ * without the canonical `ins_` prefix.
+ */
+export declare function parseAgentId(agentAddress: string): string;
+export declare function findInstance(db: DB["db"], agentAddress: string): Promise<Awaited<ReturnType<typeof db.query.agentInstance.findFirst>>>;
+export declare function requireInstance(db: DB["db"], agentAddress: string): Promise<NonNullable<Awaited<ReturnType<typeof db.query.agentInstance.findFirst>>>>;

package/dist/hub-session-lookups.js

@@ -0,0 +1,204 @@
+// Lookups that the sidecar wire layer issues against host state. These
+// are queries (one answer per question) rather than events (broadcast
+// notifications), so they live separately from the event emitter.
+//
+// Each lookup is a stateless DB or repo call. They are gathered into a
+// single struct that the hub app passes to `createSidecarRouter` as
+// `lookups`.
+import { eq, and, isNull } from "drizzle-orm";
+import { agentInstance, sessionMail, workflowDeployment, } from "@intx/db/schema";
+import { getLogger } from "@intx/log";
+import { parseAgentAddress } from "@intx/types";
+import { isWorkflowDerivedAddress } from "@intx/workflow-deploy";
+import { generateId } from "@intx/hub-common";
+const logger = getLogger(["hub", "lookups"]);
+export function createHubSessionLookups(deps) {
+    const { db, agentRepoStore } = deps;
+    return {
+        async lookupPublicKey(agentAddress) {
+            // Route by address space, not a blind two-table fallback: a
+            // workflow-derived address's key lives on its workflow_deployment
+            // row, a launched agent's on its agent_instance row, and the two
+            // spaces are disjoint. Routing (rather than falling back) means a
+            // launched agent that is missing its instance row returns null and
+            // fails its challenge visibly, instead of silently resolving against
+            // the wrong table.
+            if (isWorkflowDerivedAddress(agentAddress)) {
+                // Filter to a live ("deployed") deployment so a torn-down
+                // deployment's key can no longer satisfy a challenge. A null
+                // publicKey (deployed but not yet acked, or pre-migration) or an
+                // absent row returns null -- the challenge fails closed and the
+                // address stays unrouted rather than routing without ownership
+                // proof.
+                const row = await db
+                    .select({ publicKey: workflowDeployment.publicKey })
+                    .from(workflowDeployment)
+                    .where(and(eq(workflowDeployment.address, agentAddress), eq(workflowDeployment.status, "deployed")))
+                    .limit(1)
+                    .then((rows) => rows[0]);
+                return row?.publicKey ?? null;
+            }
+            const row = await db
+                .select({ publicKey: agentInstance.publicKey })
+                .from(agentInstance)
+                .where(and(eq(agentInstance.address, agentAddress), isNull(agentInstance.endedAt)))
+                .limit(1)
+                .then((rows) => rows[0]);
+            return row?.publicKey ?? null;
+        },
+        async lookupDeployRef(agentAddress) {
+            const agentId = parseAgentId(agentAddress);
+            return agentRepoStore.getDeployRef(agentId);
+        },
+        async persistMail({ senderAddress, recipients, raw }) {
+            const senderInstance = await requireInstance(db, senderAddress);
+            if (!senderInstance.sessionId) {
+                throw new Error(`Instance ${senderInstance.id} has no session for address "${senderAddress}"`);
+            }
+            const createdAt = new Date();
+            // Outbound record on the sender's session.
+            const outboundId = generateId("sessionMail");
+            const outboundRecord = {
+                id: outboundId,
+                sessionId: senderInstance.sessionId,
+                instanceId: senderInstance.id,
+                tenantId: senderInstance.tenantId,
+                direction: "outbound",
+                status: "delivered",
+                raw,
+                createdAt,
+            };
+            // Inbound records for each recipient that has an active agent
+            // instance. Recipients that are not agent instances (e.g. human
+            // user addresses) are skipped.
+            const recipientResults = await Promise.all(recipients.map(async (addr) => {
+                const row = await findInstance(db, addr);
+                if (row === undefined) {
+                    return null;
+                }
+                if (row.sessionId === null) {
+                    logger.warn `Active instance ${row.id} for "${addr}" has no session; skipping inbound record`;
+                    return null;
+                }
+                return { addr, instance: row, sessionId: row.sessionId };
+            }));
+            const recipientInstances = recipientResults.filter((r) => r !== null);
+            const inboundEntries = recipientInstances.map(({ addr, instance, sessionId }) => {
+                const id = generateId("sessionMail");
+                return {
+                    record: {
+                        id,
+                        sessionId,
+                        instanceId: instance.id,
+                        tenantId: instance.tenantId,
+                        direction: "inbound",
+                        status: "delivered",
+                        raw,
+                        createdAt,
+                    },
+                    result: {
+                        id,
+                        direction: "inbound",
+                        instanceId: instance.id,
+                        address: addr,
+                        createdAt,
+                    },
+                };
+            });
+            await db
+                .insert(sessionMail)
+                .values([outboundRecord, ...inboundEntries.map((e) => e.record)]);
+            return [
+                {
+                    id: outboundId,
+                    direction: "outbound",
+                    instanceId: senderInstance.id,
+                    address: senderInstance.address,
+                    createdAt,
+                },
+                ...inboundEntries.map((e) => e.result),
+            ];
+        },
+        async receiveAgentStatePack(repoId, pack, ref, commitSha) {
+            if (repoId.kind !== "agent-state") {
+                throw new Error(`hub-session lookups receiveAgentStatePack received unsupported repo kind ${JSON.stringify(repoId.kind)}`);
+            }
+            const agentAddress = repoId.id;
+            const agentId = parseAgentId(agentAddress);
+            try {
+                await agentRepoStore.receiveAgentStatePack({ kind: "agent-state", id: agentId }, pack, ref, commitSha);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.startsWith("path_violation")) {
+                    logger.warn `State pack rejected for ${agentAddress}: ${msg}`;
+                    return { accepted: false, reason: "path_violation" };
+                }
+                // Any other failure from the repo subsystem reaches the
+                // WebSocket handler as an unhandled rejection unless we catch
+                // it here. Transient failures during receivePack (the agent
+                // directory being torn down concurrently with an in-flight
+                // pack write, filesystem errors mid-rename, etc.) are
+                // recoverable from the sender's perspective — the sender can
+                // re-push. Surface every such failure as a structured pack
+                // rejection (`corrupt` is the closest existing reason — from
+                // the sender's perspective the pack failed to index) and log
+                // the underlying error so the cause stays traceable on the
+                // hub side.
+                logger.error `State pack receive failed for ${agentAddress}: ${msg}`;
+                return { accepted: false, reason: "corrupt" };
+            }
+            return { accepted: true };
+        },
+        async receiveWorkflowRunPack(repoId, pack, ref, commitSha) {
+            if (repoId.kind !== "workflow-run") {
+                throw new Error(`hub-session lookups receiveWorkflowRunPack received unsupported repo kind ${JSON.stringify(repoId.kind)}`);
+            }
+            const deploymentId = repoId.id;
+            try {
+                await agentRepoStore.receiveWorkflowRunPack({ kind: "workflow-run", id: deploymentId }, pack, ref, commitSha);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.startsWith("path_violation")) {
+                    logger.warn `Workflow-run pack rejected for ${deploymentId}: ${msg}`;
+                    return { accepted: false, reason: "path_violation" };
+                }
+                // Mirror the agent-state branch's catch-all: any other failure
+                // from the repo subsystem (filesystem races, kind-handler
+                // diagnostics surfaced as Error messages, etc.) becomes a
+                // structured `corrupt` rejection so the sender can re-push,
+                // and the underlying error is logged so the cause stays
+                // traceable on the hub side.
+                logger.error `Workflow-run pack receive failed for ${deploymentId}: ${msg}`;
+                return { accepted: false, reason: "corrupt" };
+            }
+            return { accepted: true };
+        },
+    };
+}
+/**
+ * Extract the instance id from an `<instanceId>@<domain>` agent address.
+ * Throws on any input the `@intx/types`-owned `parseAgentAddress`
+ * rejects: missing or leading `@`, empty domain, or an instance id
+ * without the canonical `ins_` prefix.
+ */
+export function parseAgentId(agentAddress) {
+    const parsed = parseAgentAddress(agentAddress);
+    if (parsed === null) {
+        throw new Error(`Invalid agent address: "${agentAddress}"`);
+    }
+    return parsed.instanceId;
+}
+export async function findInstance(db, agentAddress) {
+    return db.query.agentInstance.findFirst({
+        where: and(eq(agentInstance.address, agentAddress), isNull(agentInstance.endedAt)),
+    });
+}
+export async function requireInstance(db, agentAddress) {
+    const row = await findInstance(db, agentAddress);
+    if (!row) {
+        throw new Error(`No active instance found for address "${agentAddress}"`);
+    }
+    return row;
+}

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,122 @@
+// 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 { agentInstance, workflowDeployment } 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 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 ({ 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));
+            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}"`);
+        }
+        await db
+            .update(agentInstance)
+            .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 });
+    }));
+    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,18 @@
+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 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 { createHubSessionOrchestrator, type HubSessionOrchestrator, type HubSessionOrchestratorDeps, type HubSessionRouterFacade, } from "./hub-session-orchestrator.js";
+export { pushSourceUpdates, pushSourceUpdatesSubtree } from "./credential-push.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 { 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 { createRepoStore, subscribeKind, UserPrincipal } from "./repo-store/index.js";

package/dist/index.js

@@ -0,0 +1,16 @@
+export { createAgentRepoStore, } from "./agent-repo.js";
+export { createSessionService, SessionLaunchError, bridgeOrchestratorDeployContent, } from "./session-service.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 { createHubSessionOrchestrator, } from "./hub-session-orchestrator.js";
+export { pushSourceUpdates, pushSourceUpdatesSubtree } from "./credential-push.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 { 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/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 {};