@intx/hub-sessions 0.1.2 → 0.2.2

package/dist/skill-kind.d.ts

@@ -0,0 +1,41 @@
+import { type AuthorizeFn, type KindHandler } from "./repo-store/index.js";
+export type SkillHubPrincipal = {
+    readonly kind: "hub";
+};
+export type SkillSidecarPrincipal = {
+    readonly kind: "sidecar";
+    readonly agentId: string;
+};
+export type SkillPrincipal = SkillHubPrincipal | SkillSidecarPrincipal;
+/**
+ * arktype schema for the SKILL.md frontmatter. Required fields are
+ * `name` and `description`; the Claude Code superset of optional fields
+ * (`when_to_use`, `allowed-tools`, `paths`, `model`, ...) is accepted
+ * via `onUndeclaredKey("ignore")` but not enforced.
+ *
+ * The forbidden-name narrow rejects `"anthropic"` and `"claude"`
+ * because those values are reserved by the upstream agentskills.io
+ * spec for vendor-owned skill packs.
+ */
+export declare const skillFrontmatterSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    name: string;
+    description: string;
+}, {}>;
+export type SkillFrontmatter = typeof skillFrontmatterSchema.infer;
+export type SkillIndexEntry = {
+    /** Equal to the containing directory name and to `frontmatter.name`. */
+    name: string;
+    description: string;
+    /** Full parsed frontmatter, including any accepted optional fields. */
+    frontmatter: Record<string, unknown>;
+    /** Path of the skill subdirectory relative to the asset mount, with trailing slash. */
+    workspaceSubpath: string;
+};
+/**
+ * Returns the parsed skill index for `(assetId, ref)`, or an empty
+ * array if no index has been populated yet. The index is refreshed by
+ * the kind handler's `onRefUpdated` hook after each successful write.
+ */
+export declare function getSkillIndex(assetId: string, ref: string): SkillIndexEntry[];
+export declare const skillKindHandler: KindHandler;
+export declare const skillAuthorize: AuthorizeFn;

package/dist/skill-kind.js

@@ -0,0 +1,288 @@
+import { type } from "arktype";
+import { getLogger } from "@intx/log";
+import { glob, repoActionToGrantVerb } from "@intx/hub-common";
+import { UserPrincipal, } from "./repo-store/index.js";
+const logger = getLogger(["hub-sessions", "skill-kind"]);
+/**
+ * arktype schema for the SKILL.md frontmatter. Required fields are
+ * `name` and `description`; the Claude Code superset of optional fields
+ * (`when_to_use`, `allowed-tools`, `paths`, `model`, ...) is accepted
+ * via `onUndeclaredKey("ignore")` but not enforced.
+ *
+ * The forbidden-name narrow rejects `"anthropic"` and `"claude"`
+ * because those values are reserved by the upstream agentskills.io
+ * spec for vendor-owned skill packs.
+ */
+export const skillFrontmatterSchema = type({
+    name: type(/^[a-z0-9]+(-[a-z0-9]+)*$/)
+        .and("string<=64")
+        .narrow((n, ctx) => {
+        if (n === "anthropic" || n === "claude") {
+            return ctx.mustBe(`not the reserved name "anthropic" or "claude"`);
+        }
+        return true;
+    }),
+    description: type("1 <= string <= 1024").and(type(/^(?!.*<[^>]+>).*$/s)),
+}).onUndeclaredKey("ignore");
+function cacheKey(assetId, ref) {
+    return `${assetId}\u0000${ref}`;
+}
+const skillIndex = new Map();
+const pendingIndex = new Map();
+/**
+ * Returns the parsed skill index for `(assetId, ref)`, or an empty
+ * array if no index has been populated yet. The index is refreshed by
+ * the kind handler's `onRefUpdated` hook after each successful write.
+ */
+export function getSkillIndex(assetId, ref) {
+    return skillIndex.get(cacheKey(assetId, ref)) ?? [];
+}
+const FRONTMATTER_DELIMITER = "---";
+const YamlMapping = type("Record<string, unknown>");
+function parseSkillMd(body) {
+    const lines = body.split(/\r?\n/);
+    if (lines[0] !== FRONTMATTER_DELIMITER) {
+        throw new Error("SKILL.md is missing YAML frontmatter delimiter");
+    }
+    let endIdx = -1;
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i] === FRONTMATTER_DELIMITER) {
+            endIdx = i;
+            break;
+        }
+    }
+    if (endIdx === -1) {
+        throw new Error("SKILL.md frontmatter has no closing delimiter");
+    }
+    const yamlText = lines.slice(1, endIdx).join("\n");
+    const parsed = Bun.YAML.parse(yamlText);
+    const validated = YamlMapping(parsed);
+    if (validated instanceof type.errors) {
+        throw new Error(`SKILL.md frontmatter must be a YAML mapping: ${validated.summary}`);
+    }
+    return { frontmatter: validated };
+}
+async function parseSkillEntry(subdir, readBlob) {
+    const skillPath = `${subdir}/SKILL.md`;
+    let raw;
+    try {
+        raw = await readBlob(skillPath);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            reason: `skill ${subdir} is missing SKILL.md: ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+    const body = new TextDecoder().decode(raw);
+    let parsed;
+    try {
+        parsed = parseSkillMd(body);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            reason: `skill ${subdir} frontmatter parse failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+    const result = skillFrontmatterSchema(parsed.frontmatter);
+    if (result instanceof type.errors) {
+        return {
+            ok: false,
+            reason: `skill ${subdir} frontmatter is invalid: ${result.summary}`,
+        };
+    }
+    if (result.name !== subdir) {
+        return {
+            ok: false,
+            reason: `skill ${subdir} frontmatter.name ${JSON.stringify(result.name)} does not match directory name`,
+        };
+    }
+    return {
+        ok: true,
+        entry: {
+            name: result.name,
+            description: result.description,
+            frontmatter: parsed.frontmatter,
+            workspaceSubpath: `${subdir}/`,
+        },
+    };
+}
+async function buildSkillIndex(topLevelTreePaths, readBlob, listDir) {
+    const entries = [];
+    // Sort so the index ordering is deterministic across reads.
+    const candidates = [...topLevelTreePaths].sort();
+    for (const candidate of candidates) {
+        // Skill subdirectories are arbitrarily named (`<skill-name>/`), so
+        // there is no enumerable allowlist of names the way the workflow,
+        // package-registry, and agent-state handlers use. The structural
+        // distinction is tree-vs-blob: a top-level tree entry is a skill
+        // subdir, a top-level blob (e.g. `.gitignore` seeded by the
+        // genesis init) is not.
+        //
+        // Probe via `listDir`. The substrate's two implementations
+        // disagree on the not-a-tree signal — the receivePack closures
+        // throw, the writeTree closures return an empty array — so this
+        // probe accepts either signal as "not a directory" and skips the
+        // entry. Git does not store empty trees, so an empty `listDir`
+        // result is equivalent to "this name is not a directory in the
+        // prospective tree".
+        let children;
+        try {
+            children = await listDir(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (children.length === 0)
+            continue;
+        const outcome = await parseSkillEntry(candidate, readBlob);
+        if (!outcome.ok) {
+            return { ok: false, reason: outcome.reason };
+        }
+        entries.push(outcome.entry);
+    }
+    return { ok: true, entries };
+}
+export const skillKindHandler = {
+    kind: "skill",
+    directoryPrefix: "assets/skill",
+    async validatePush({ repoId, ref, topLevelTreePaths, readBlob, listDir, }) {
+        // Drop any staged entry from a previous attempt first. The
+        // substrate calls validatePush before advancing the ref, so a prior
+        // validation that was accepted but never followed by onRefUpdated
+        // (e.g. the commit step threw after validation succeeded) would
+        // otherwise leave a stale entry that a later rejected attempt
+        // would silently inherit.
+        const key = cacheKey(repoId.id, ref);
+        pendingIndex.delete(key);
+        const result = await buildSkillIndex(topLevelTreePaths, readBlob, listDir);
+        if (!result.ok) {
+            logger.debug `skill validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${result.reason}`;
+            return { ok: false, reason: result.reason };
+        }
+        // Stage the parsed index against (repoId.id, ref). The substrate
+        // calls onRefUpdated immediately after the ref is advanced and we
+        // promote the staged entry into the live cache there.
+        pendingIndex.set(key, result.entries);
+        return { ok: true };
+    },
+    onRefUpdated({ repoId, ref }) {
+        const key = cacheKey(repoId.id, ref);
+        const staged = pendingIndex.get(key);
+        if (staged === undefined) {
+            throw new Error(`skillKindHandler.onRefUpdated: no validated tree pending for ${repoId.id} @ ${ref}`);
+        }
+        pendingIndex.delete(key);
+        skillIndex.set(key, staged);
+    },
+};
+const SidecarPrincipal = type({
+    kind: "'sidecar'",
+    agentId: "string",
+});
+export const skillAuthorize = (principal, repoId, ref, action) => {
+    if (repoId.kind !== "skill") {
+        return {
+            allowed: false,
+            reason: `skill authorize received non-skill repo ${repoId.kind}/${repoId.id}`,
+        };
+    }
+    if (principal.kind === "hub") {
+        return { allowed: true };
+    }
+    if (principal.kind === "sidecar") {
+        const parsed = SidecarPrincipal(principal);
+        if (parsed instanceof type.errors) {
+            return {
+                allowed: false,
+                reason: `sidecar principal is malformed: ${parsed.summary}`,
+            };
+        }
+        switch (action) {
+            case "createPack":
+            case "resolveRef":
+                return { allowed: true };
+            case "init":
+            case "writeTree":
+            case "receivePack":
+                return {
+                    allowed: false,
+                    reason: `sidecars may only read skill assets, not ${action}`,
+                };
+            default: {
+                const _exhaustive = action;
+                return {
+                    allowed: false,
+                    reason: `unhandled action: ${String(_exhaustive)}`,
+                };
+            }
+        }
+    }
+    if (principal.kind === "user") {
+        // The route layer has already pre-resolved the grant verdict and
+        // attached it as `authz`. The substrate does NOT re-query the
+        // grant store here; it (a) checks the bearer-token's claims
+        // bound the requested (ref, action) and have not expired, and
+        // (b) sanity-checks that the pre-resolved verdict targets this
+        // exact resource and grant verb. Both gates must pass before the
+        // verdict's `effect` is honoured.
+        const parsed = UserPrincipal(principal);
+        if (parsed instanceof type.errors) {
+            return {
+                allowed: false,
+                reason: `user principal is malformed: ${parsed.summary}`,
+            };
+        }
+        if (!parsed.tokenClaims.actions.includes(action)) {
+            return {
+                allowed: false,
+                reason: `token does not grant action ${action}`,
+            };
+        }
+        // `ref === "*"` is the substrate's sentinel for a bulk read used
+        // by `listRefs`. The advertise-refs layer applies the per-ref
+        // refPattern filter on the listing it returns, so gating the bulk
+        // read on refPattern here would prevent any token with a
+        // narrow-pattern (e.g. `refs/heads/main`) from listing refs at
+        // all. Only the action and expiry are enforced for the bulk read;
+        // every other call site passes a concrete ref and is gated below.
+        if (ref !== "*" && !glob.match(parsed.tokenClaims.refPattern, ref)) {
+            return {
+                allowed: false,
+                reason: `token refPattern ${parsed.tokenClaims.refPattern} does not match ${ref}`,
+            };
+        }
+        if (Date.now() >= parsed.tokenClaims.expiresAt) {
+            return {
+                allowed: false,
+                reason: `token expired at ${parsed.tokenClaims.expiresAt}`,
+            };
+        }
+        const expectedResource = `asset:${repoId.id}`;
+        if (parsed.authz.resource !== expectedResource) {
+            return {
+                allowed: false,
+                reason: `authz verdict resource ${parsed.authz.resource} does not match ${expectedResource}`,
+            };
+        }
+        const expectedGrantVerb = repoActionToGrantVerb(action);
+        if (parsed.authz.grantVerb !== expectedGrantVerb) {
+            return {
+                allowed: false,
+                reason: `authz verdict grantVerb ${parsed.authz.grantVerb} does not match ${expectedGrantVerb}`,
+            };
+        }
+        if (parsed.authz.effect === "allow") {
+            return { allowed: true };
+        }
+        return {
+            allowed: false,
+            reason: `authz verdict denied for ${expectedResource} ${expectedGrantVerb}`,
+        };
+    }
+    return {
+        allowed: false,
+        reason: `unknown principal kind: ${principal.kind}`,
+    };
+};

package/dist/substrate.d.ts

@@ -0,0 +1,8 @@
+export { DEFAULT_CONSUMED_RETENTION_MS, dequeueToProcessing, enqueueInbox, markConsumed, readOwnedMessageIds, readProcessingEntry, replayProcessingToInbox, WORKFLOW_RUN_AGENT_STATE_PREFIX, } from "./workflow-run-kind.js";
+export type { WorkflowRunSupervisorPrincipal, WorkflowRunWorkflowProcessPrincipal, DequeueToProcessingResult, EnqueueInboxArgs, EnqueueInboxResult, MarkConsumedArgs, MarkConsumedResult, ReplayProcessingToInboxOpts, ReplayProcessingToInboxResult, } from "./workflow-run-kind.js";
+export { encodeCombinedEventLog, splitCombinedEventLog, WORKFLOW_RUN_EVENTS_FILE, } from "./workflow-run-event-log.js";
+export { workflowDefinitionEnvelopeSchema } from "./workflow-kind.js";
+export { subscribeKind } from "./repo-store/subscribe-kind.js";
+export type { SubscribeKindEntry } from "./repo-store/subscribe-kind.js";
+export { createAgentRepoStore } from "./agent-repo.js";
+export type { Principal, RepoId, RepoStore, WriteResult, InitRepoOpts, NewlyTerminalRun, } from "./repo-store/types.js";

package/dist/substrate.js

@@ -0,0 +1,21 @@
+// The db-free substrate layer of this package.
+//
+// `@intx/hub-sessions` holds two layers: the git-backed repo-store substrate
+// (the `RepoStore`, the workflow-run claim-check and event-log primitives, the
+// kind-handler protocol) and the db-backed control-plane services (sessions,
+// credential push, the websocket layer). The substrate layer never imports
+// `@intx/db`; the services layer does. The package barrel (`index.ts`)
+// re-exports both, so importing any symbol through it pulls drizzle and the
+// rest of the hub data layer into module-evaluation.
+//
+// This entry exposes only the substrate layer, so any consumer that needs
+// repo/substrate access without the control-plane services -- for example a
+// process that reads and writes the agent-state and workflow-run repos but
+// runs nowhere near a database -- can import it without dragging `@intx/db`
+// into its boot graph. Every symbol re-exported here is defined in a db-free
+// module. The barrel still re-exports all of these for hub-side consumers.
+export { DEFAULT_CONSUMED_RETENTION_MS, dequeueToProcessing, enqueueInbox, markConsumed, readOwnedMessageIds, readProcessingEntry, replayProcessingToInbox, WORKFLOW_RUN_AGENT_STATE_PREFIX, } from "./workflow-run-kind.js";
+export { encodeCombinedEventLog, splitCombinedEventLog, WORKFLOW_RUN_EVENTS_FILE, } from "./workflow-run-event-log.js";
+export { workflowDefinitionEnvelopeSchema } from "./workflow-kind.js";
+export { subscribeKind } from "./repo-store/subscribe-kind.js";
+export { createAgentRepoStore } from "./agent-repo.js";

package/dist/workflow-kind.d.ts

@@ -0,0 +1,21 @@
+import { type AuthorizeFn, type KindHandler } from "./repo-store/index.js";
+export type WorkflowHubPrincipal = {
+    readonly kind: "hub";
+};
+export type WorkflowSidecarPrincipal = {
+    readonly kind: "sidecar";
+    readonly agentId: string;
+};
+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 workflowDefinitionEnvelopeSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    id: string;
+    triggers: unknown[];
+    steps: Record<string, unknown>;
+    stepOrder: string[];
+    state?: Record<string, unknown>;
+}, {}>;
+export declare const workflowKindHandler: KindHandler;
+export declare const workflowAuthorize: AuthorizeFn;

package/dist/workflow-kind.js

@@ -0,0 +1,263 @@
+// 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:
+//
+//   - `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.
+//
+// Authz:
+//   - hub principal: full access.
+//   - sidecar principal: read-only (createPack, resolveRef).
+//   - user principal: gated by bearer-token claims and the route
+//     layer's pre-resolved authz verdict, mirroring the convention
+//     used by skill assets.
+import { type } from "arktype";
+import { getLogger } from "@intx/log";
+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,
+]);
+/**
+ * Structural arktype validator for the `workflow.json` envelope. The
+ * substrate checks the cross-cutting shape of `WorkflowDefinition`
+ * (presence and primitive type of `id`, `triggers`, `steps`,
+ * `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.
+ */
+const StepsObject = type("Record<string, unknown>").narrow((value, ctx) => {
+    if (Array.isArray(value)) {
+        return ctx.mustBe("a JSON object, not an array");
+    }
+    return true;
+});
+const StateObject = type("Record<string, unknown>").narrow((value, ctx) => {
+    if (Array.isArray(value)) {
+        return ctx.mustBe("a JSON object, not an array");
+    }
+    return true;
+});
+export const workflowDefinitionEnvelopeSchema = type({
+    id: "string > 0",
+    triggers: "unknown[]",
+    steps: StepsObject,
+    stepOrder: "string[]",
+    "state?": StateObject,
+}).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",
+});
+async function readJSONBlob(path, readBlob) {
+    let raw;
+    try {
+        raw = await readBlob(path);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            reason: `${path} could not be read from the tree: ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+    const text = new TextDecoder().decode(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            reason: `${path} is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+    return { ok: true, value: parsed };
+}
+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}"`,
+                };
+            }
+        }
+        // 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 };
+    },
+    onRefUpdated() {
+        // No cached index today. Consumers read the workflow.json and
+        // capability-declarations.json through the substrate's blob-read
+        // API at session time.
+    },
+};
+export const workflowAuthorize = (principal, repoId, ref, action) => {
+    if (repoId.kind !== "workflow") {
+        return {
+            allowed: false,
+            reason: `workflow authorize received non-workflow repo ${repoId.kind}/${repoId.id}`,
+        };
+    }
+    if (principal.kind === "hub") {
+        return { allowed: true };
+    }
+    if (principal.kind === "sidecar") {
+        const parsed = SidecarPrincipal(principal);
+        if (parsed instanceof type.errors) {
+            return {
+                allowed: false,
+                reason: `sidecar principal is malformed: ${parsed.summary}`,
+            };
+        }
+        switch (action) {
+            case "createPack":
+            case "resolveRef":
+                return { allowed: true };
+            case "init":
+            case "writeTree":
+            case "receivePack":
+                return {
+                    allowed: false,
+                    reason: `sidecars may only read workflow assets, not ${action}`,
+                };
+            default: {
+                const _exhaustive = action;
+                return {
+                    allowed: false,
+                    reason: `unhandled action: ${String(_exhaustive)}`,
+                };
+            }
+        }
+    }
+    if (principal.kind === "user") {
+        // The route layer has already pre-resolved the grant verdict and
+        // attached it as `authz`. The substrate does NOT re-query the
+        // grant store here; it (a) checks the bearer-token's claims
+        // bound the requested (ref, action) and have not expired, and
+        // (b) sanity-checks that the pre-resolved verdict targets this
+        // exact resource and grant verb. Both gates must pass before the
+        // verdict's `effect` is honoured.
+        const parsed = UserPrincipal(principal);
+        if (parsed instanceof type.errors) {
+            return {
+                allowed: false,
+                reason: `user principal is malformed: ${parsed.summary}`,
+            };
+        }
+        if (!parsed.tokenClaims.actions.includes(action)) {
+            return {
+                allowed: false,
+                reason: `token does not grant action ${action}`,
+            };
+        }
+        // `ref === "*"` is the substrate's sentinel for the bulk read
+        // performed by `listRefs`. Per-ref filtering is the advertise-refs
+        // layer's responsibility, so the bulk read is gated on action and
+        // expiry alone.
+        if (ref !== "*" && !glob.match(parsed.tokenClaims.refPattern, ref)) {
+            return {
+                allowed: false,
+                reason: `token refPattern ${parsed.tokenClaims.refPattern} does not match ${ref}`,
+            };
+        }
+        if (Date.now() >= parsed.tokenClaims.expiresAt) {
+            return {
+                allowed: false,
+                reason: `token expired at ${parsed.tokenClaims.expiresAt}`,
+            };
+        }
+        const expectedResource = `asset:${repoId.id}`;
+        if (parsed.authz.resource !== expectedResource) {
+            return {
+                allowed: false,
+                reason: `authz verdict resource ${parsed.authz.resource} does not match ${expectedResource}`,
+            };
+        }
+        const expectedGrantVerb = repoActionToGrantVerb(action);
+        if (parsed.authz.grantVerb !== expectedGrantVerb) {
+            return {
+                allowed: false,
+                reason: `authz verdict grantVerb ${parsed.authz.grantVerb} does not match ${expectedGrantVerb}`,
+            };
+        }
+        if (parsed.authz.effect === "allow") {
+            return { allowed: true };
+        }
+        return {
+            allowed: false,
+            reason: `authz verdict denied for ${expectedResource} ${expectedGrantVerb}`,
+        };
+    }
+    return {
+        allowed: false,
+        reason: `unknown principal kind: ${principal.kind}`,
+    };
+};

package/dist/workflow-run-event-log.d.ts

@@ -0,0 +1,21 @@
+/** Filename of a run's combined event log, a sibling of its `events/` dir. */
+export declare const WORKFLOW_RUN_EVENTS_FILE = "events.jsonl";
+/**
+ * Split a combined event-log file's content into the per-event JSON texts it
+ * holds, in file order. Each non-empty line is the verbatim text of what was
+ * an `events/<seq>.json` blob; the trailing newline yields no extra entry.
+ * Event JSON never contains a literal newline (JSON escapes them), so a line
+ * split is a faithful inverse of the encode side.
+ */
+export declare function splitCombinedEventLog(content: string): string[];
+/**
+ * Join per-event blobs (in seq order) into a combined event-log file: each
+ * blob's exact bytes followed by a newline. Operating on bytes -- not
+ * decoded strings -- keeps the sealed file a *verbatim* concatenation of
+ * the per-event blobs, which matters because each event is signed over its
+ * own bytes; a decode/re-encode round-trip could alter them. This is the
+ * single source of the combined-file byte layout shared by the compaction
+ * writer and the validator's byte-equality bridge, so the two cannot
+ * drift. An empty input yields an empty file.
+ */
+export declare function encodeCombinedEventLog(perEventBlobs: readonly Uint8Array[]): Uint8Array;