@intx/hub-sessions 0.2.2 → 0.3.0

package/dist/workflow-dispatch-service.d.ts

@@ -0,0 +1,40 @@
+import type { DBExecutor, EnqueueWorkflowRunDispatchArgs, EnqueueWorkflowRunDispatchResult, EnqueueWorkflowSignalDispatchArgs, SidecarAllocationStore, WorkflowRunDispatchStore } from "@intx/db";
+import type { SidecarAllocationRouter } from "./ws/sidecar-handler.js";
+type DispatchStore = Pick<WorkflowRunDispatchStore, "acknowledge" | "claimNextPending" | "enqueue" | "enqueueSignal" | "requeueUnsettled" | "scheduleRetry" | "settle">;
+type AllocationStore = Pick<SidecarAllocationStore, "findByAnchorRunId">;
+type DispatchRouter = Pick<SidecarAllocationRouter, "sendSignalDeliverToAllocation" | "sendWorkflowRunDispatchToAllocation">;
+export type WorkflowDispatchAcknowledgement = {
+    readonly allocationId: string;
+    readonly anchorRunId: string;
+    readonly generation: number;
+    readonly messageId: string;
+};
+export type WorkflowDispatchService = {
+    enqueue(args: EnqueueWorkflowRunDispatchArgs, tx?: DBExecutor): Promise<EnqueueWorkflowRunDispatchResult>;
+    enqueueSignal(args: EnqueueWorkflowSignalDispatchArgs, tx?: DBExecutor): Promise<EnqueueWorkflowRunDispatchResult>;
+    acknowledge(args: WorkflowDispatchAcknowledgement): Promise<void>;
+    settle(anchorRunId: string, messageId: string): Promise<void>;
+    requeueForReadyAllocation(anchorRunId: string): Promise<number>;
+    reconcileNext(): Promise<boolean>;
+    reconcileUntilIdle(maxIterations?: number): Promise<number>;
+    wake(): void;
+};
+export type WorkflowDispatchServiceDeps = {
+    readonly dispatchStore: DispatchStore;
+    readonly allocationStore: AllocationStore;
+    readonly router: DispatchRouter;
+    /** Resolve the deployment anchor's durable routing address. */
+    readonly resolveAnchorAddress: (anchorRunId: string) => Promise<string | null>;
+    readonly leaseDurationMs?: number;
+    readonly retryDelayMs?: (attempt: number) => number;
+    readonly now?: () => Date;
+    readonly createLeaseId?: () => string;
+};
+/**
+ * Drives Hub-owned workflow triggers onto exclusive sidecars. The database
+ * row is the delivery authority: websocket acceptance never deletes the raw
+ * payload, and a generation replacement requeues every row that has not been
+ * settled by the workflow-run Git claim-check.
+ */
+export declare function createWorkflowDispatchService({ dispatchStore, allocationStore, router, resolveAnchorAddress, leaseDurationMs, retryDelayMs, now, createLeaseId, }: WorkflowDispatchServiceDeps): WorkflowDispatchService;
+export {};

package/dist/workflow-dispatch-service.js

@@ -0,0 +1,146 @@
+import { getLogger } from "@intx/log";
+import { base64Encode, hexEncode } from "@intx/types";
+import { SignalDeliverFrame } from "@intx/types/sidecar";
+const logger = getLogger(["hub", "workflow-dispatch"]);
+const DEFAULT_LEASE_DURATION_MS = 30_000;
+function defaultRetryDelay(attempt) {
+    return Math.min(500 * 2 ** Math.min(attempt, 6), 30_000);
+}
+function randomLeaseId() {
+    return `dispatch_lease_${hexEncode(crypto.getRandomValues(new Uint8Array(16)))}`;
+}
+function targetForReadyAllocation(allocation) {
+    if (allocation.status !== "allocated" ||
+        allocation.ensureAcceptedGeneration !== allocation.generation ||
+        allocation.connectDeadline !== undefined) {
+        return null;
+    }
+    return {
+        allocationId: allocation.id,
+        generation: allocation.generation,
+    };
+}
+/**
+ * Drives Hub-owned workflow triggers onto exclusive sidecars. The database
+ * row is the delivery authority: websocket acceptance never deletes the raw
+ * payload, and a generation replacement requeues every row that has not been
+ * settled by the workflow-run Git claim-check.
+ */
+export function createWorkflowDispatchService({ dispatchStore, allocationStore, router, resolveAnchorAddress, leaseDurationMs = DEFAULT_LEASE_DURATION_MS, retryDelayMs = defaultRetryDelay, now = () => new Date(), createLeaseId = randomLeaseId, }) {
+    if (leaseDurationMs <= 0) {
+        throw new Error("leaseDurationMs must be positive");
+    }
+    let drainPromise = null;
+    function retryAt(attempt) {
+        return new Date(now().getTime() + retryDelayMs(attempt));
+    }
+    async function retry(dispatch, leaseId, code, message) {
+        await dispatchStore.scheduleRetry({
+            dispatchId: dispatch.id,
+            nextAttemptAt: retryAt(dispatch.attemptCount),
+            code,
+            message,
+            expectedLeaseId: leaseId,
+            now: now(),
+        });
+    }
+    async function reconcileNext() {
+        const leaseId = createLeaseId();
+        const dispatch = await dispatchStore.claimNextPending({
+            leaseId,
+            leaseDurationMs,
+        });
+        if (dispatch === null)
+            return false;
+        const allocation = await allocationStore.findByAnchorRunId(dispatch.anchorRunId);
+        if (allocation === null) {
+            await retry(dispatch, leaseId, "allocation_missing", `No sidecar allocation exists for workflow anchor ${dispatch.anchorRunId}`);
+            return true;
+        }
+        const target = targetForReadyAllocation(allocation);
+        if (target === null) {
+            await retry(dispatch, leaseId, "allocation_not_ready", `Sidecar allocation ${allocation.id} is not ready for delivery`);
+            return true;
+        }
+        const agentAddress = await resolveAnchorAddress(dispatch.anchorRunId);
+        if (agentAddress === null) {
+            await retry(dispatch, leaseId, "anchor_address_missing", `Workflow anchor ${dispatch.anchorRunId} has no routing address`);
+            return true;
+        }
+        try {
+            if (dispatch.kind === "signal") {
+                const signal = SignalDeliverFrame.assert(JSON.parse(new TextDecoder().decode(dispatch.rawMessage)));
+                await router.sendSignalDeliverToAllocation(target, {
+                    agentAddress: signal.agentAddress,
+                    runId: signal.runId,
+                    signalName: signal.signalName,
+                    signalId: signal.signalId,
+                    payload: signal.payload,
+                });
+            }
+            else {
+                await router.sendWorkflowRunDispatchToAllocation(target, agentAddress, 
+                // Every trigger of a deployment uses its stable mail address as the
+                // supervisor run id.
+                agentAddress, dispatch.stepGrants, base64Encode(dispatch.rawMessage), dispatch.messageId);
+            }
+            // Keep the delivery lease until the sidecar acknowledges its durable
+            // inbox write. If that ack never arrives, lease expiry makes the same
+            // immutable payload claimable again.
+        }
+        catch (error) {
+            await retry(dispatch, leaseId, "dispatch_unroutable", error instanceof Error ? error.message : String(error));
+        }
+        return true;
+    }
+    async function reconcileUntilIdle(maxIterations = 100) {
+        let reconciled = 0;
+        while (reconciled < maxIterations && (await reconcileNext())) {
+            reconciled += 1;
+        }
+        return reconciled;
+    }
+    function wake() {
+        if (drainPromise !== null)
+            return;
+        drainPromise = Promise.resolve()
+            .then(async () => {
+            await reconcileUntilIdle();
+        })
+            .catch((error) => {
+            logger.error `Workflow dispatch reconciliation failed: ${error instanceof Error ? error.message : String(error)}`;
+        })
+            .finally(() => {
+            drainPromise = null;
+        });
+    }
+    return {
+        async enqueue(args, tx) {
+            const result = await dispatchStore.enqueue(args, tx);
+            wake();
+            return result;
+        },
+        async enqueueSignal(args, tx) {
+            const result = await dispatchStore.enqueueSignal(args, tx);
+            wake();
+            return result;
+        },
+        async acknowledge(args) {
+            await dispatchStore.acknowledge({
+                ...args,
+                now: now(),
+            });
+        },
+        async settle(anchorRunId, messageId) {
+            await dispatchStore.settle(anchorRunId, messageId, now());
+        },
+        async requeueForReadyAllocation(anchorRunId) {
+            const count = await dispatchStore.requeueUnsettled(anchorRunId);
+            wake();
+            return count;
+        },
+        reconcileNext,
+        reconcileUntilIdle,
+        wake,
+    };
+}

package/dist/workflow-dispatch-settlement.d.ts

@@ -0,0 +1,29 @@
+import type { CommittedReads } from "./repo-store/index.js";
+export type ConsumedWorkflowDispatch = {
+    readonly messageId: string;
+    readonly address: string;
+    readonly rejection?: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export type ReceivedWorkflowSignal = {
+    readonly runId: string;
+    readonly signalId: string;
+};
+export type AcceptedWorkflowDispatch = {
+    readonly runId: string;
+    readonly messageId: string;
+    readonly kind: "mail" | "signal";
+};
+/** Enumerate dispatches durably accepted by one live or sealed run log. */
+export declare function listAcceptedWorkflowDispatches(reads: CommittedReads, runId: string, targetMessageIds?: ReadonlySet<string>): Promise<AcceptedWorkflowDispatch[]>;
+/** Enumerate durable SignalReceived ids from one live or sealed run log. */
+export declare function listReceivedWorkflowSignals(reads: CommittedReads, runId: string): Promise<ReceivedWorkflowSignal[]>;
+/**
+ * Enumerate the workflow-run claim-check's retained consumed index. The kind
+ * validator guarantees this tree shape before the ref advances; the runtime
+ * validator here keeps the Git-to-database projection fail-closed if that
+ * invariant is ever violated.
+ */
+export declare function listConsumedWorkflowDispatches(reads: CommittedReads): Promise<ConsumedWorkflowDispatch[]>;

package/dist/workflow-dispatch-settlement.js

@@ -0,0 +1,140 @@
+import { type } from "arktype";
+import { splitCombinedEventLog, WORKFLOW_RUN_EVENTS_FILE, } from "./workflow-run-event-log.js";
+import { WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "./workflow-run-kind.js";
+const ConsumedEnvelope = type({
+    messageId: "string",
+    address: "string",
+    "rejection?": {
+        code: "string > 0",
+        message: "string > 0",
+    },
+    "+": "ignore",
+});
+const SignalReceived = type({
+    type: "'SignalReceived'",
+    signalId: "string",
+    "+": "ignore",
+});
+const RunStarted = type({
+    type: "'RunStarted'",
+    "consumedMessageId?": "string",
+    "+": "ignore",
+});
+function projectAcceptedDispatch(raw, path) {
+    let decoded;
+    try {
+        decoded = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new Error(`workflow_dispatch_event_invalid_json: ${path}`, {
+            cause,
+        });
+    }
+    if (typeof decoded !== "object" || decoded === null || !("type" in decoded)) {
+        return null;
+    }
+    if (decoded.type === "SignalReceived") {
+        const signal = SignalReceived(decoded);
+        if (signal instanceof type.errors) {
+            throw new Error(`workflow_dispatch_signal_invalid: ${path}: ${signal.summary}`);
+        }
+        return { kind: "signal", messageId: signal.signalId };
+    }
+    if (decoded.type === "RunStarted") {
+        const started = RunStarted(decoded);
+        if (started instanceof type.errors) {
+            throw new Error(`workflow_dispatch_run_started_invalid: ${path}: ${started.summary}`);
+        }
+        return started.consumedMessageId === undefined
+            ? null
+            : { kind: "mail", messageId: started.consumedMessageId };
+    }
+    return null;
+}
+/** Enumerate dispatches durably accepted by one live or sealed run log. */
+export async function listAcceptedWorkflowDispatches(reads, runId, targetMessageIds) {
+    if (targetMessageIds?.size === 0)
+        return [];
+    const accepted = [];
+    const remaining = targetMessageIds === undefined ? undefined : new Set(targetMessageIds);
+    const accept = (dispatch) => {
+        if (dispatch === null)
+            return;
+        if (remaining !== undefined && !remaining.delete(dispatch.messageId))
+            return;
+        accepted.push({ runId, ...dispatch });
+    };
+    const runPath = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}`;
+    const children = await reads.listDir(runPath);
+    const combined = children.find((entry) => entry.type === "blob" && entry.name === WORKFLOW_RUN_EVENTS_FILE);
+    if (combined !== undefined) {
+        const raw = new TextDecoder().decode(await reads.readBlobByOid(combined.oid));
+        const lines = splitCombinedEventLog(raw);
+        for (let index = lines.length - 1; index >= 0; index -= 1) {
+            const line = lines[index];
+            if (line === undefined)
+                continue;
+            accept(projectAcceptedDispatch(line, `${runPath}/${WORKFLOW_RUN_EVENTS_FILE}:${String(index + 1)}`));
+            if (remaining?.size === 0)
+                break;
+        }
+        return accepted.reverse();
+    }
+    const eventsPath = `${runPath}/${WORKFLOW_RUN_EVENTS_DIR}`;
+    const eventEntries = (await reads.listDir(eventsPath))
+        .filter((entry) => entry.type === "blob" && entry.name.endsWith(".json"))
+        .sort((left, right) => right.name.localeCompare(left.name, undefined, {
+        numeric: true,
+    }));
+    for (const eventEntry of eventEntries) {
+        const raw = new TextDecoder().decode(await reads.readBlobByOid(eventEntry.oid));
+        accept(projectAcceptedDispatch(raw, `${eventsPath}/${eventEntry.name}`));
+        if (remaining?.size === 0)
+            break;
+    }
+    return accepted.reverse();
+}
+/** Enumerate durable SignalReceived ids from one live or sealed run log. */
+export async function listReceivedWorkflowSignals(reads, runId) {
+    return (await listAcceptedWorkflowDispatches(reads, runId))
+        .filter((dispatch) => dispatch.kind === "signal")
+        .map((dispatch) => ({ runId, signalId: dispatch.messageId }));
+}
+/**
+ * Enumerate the workflow-run claim-check's retained consumed index. The kind
+ * validator guarantees this tree shape before the ref advances; the runtime
+ * validator here keeps the Git-to-database projection fail-closed if that
+ * invariant is ever violated.
+ */
+export async function listConsumedWorkflowDispatches(reads) {
+    const consumed = [];
+    for (const addressEntry of await reads.listDir(WORKFLOW_RUN_ADDRESSES_PREFIX)) {
+        if (addressEntry.type !== "tree")
+            continue;
+        const consumedPath = `${WORKFLOW_RUN_ADDRESSES_PREFIX}/${addressEntry.name}/${WORKFLOW_RUN_CONSUMED_DIR}`;
+        for (const entry of await reads.listDir(consumedPath)) {
+            if (entry.type !== "blob" || !entry.name.endsWith(".json"))
+                continue;
+            const raw = await reads.readBlobByOid(entry.oid);
+            let decoded;
+            try {
+                decoded = JSON.parse(new TextDecoder().decode(raw));
+            }
+            catch (cause) {
+                throw new Error(`workflow_dispatch_consumed_invalid_json: ${consumedPath}/${entry.name}`, { cause });
+            }
+            const envelope = ConsumedEnvelope(decoded);
+            if (envelope instanceof type.errors) {
+                throw new Error(`workflow_dispatch_consumed_invalid: ${consumedPath}/${entry.name}: ${envelope.summary}`);
+            }
+            consumed.push({
+                messageId: envelope.messageId,
+                address: envelope.address,
+                ...(envelope.rejection !== undefined
+                    ? { rejection: envelope.rejection }
+                    : {}),
+            });
+        }
+    }
+    return consumed;
+}

package/dist/workflow-kind.d.ts

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

package/dist/workflow-kind.js

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