@intx/hub-sessions 0.2.2 → 0.4.0

package/dist/repo-store/subscribe-kind.js

@@ -1,17 +1,5 @@
-import fs from "node:fs";
-import git from "isomorphic-git";
 import { type } from "arktype";
-import { hasCode } from "@intx/types";
-/**
- * Path-layout constants for the workflow-run repo's event log. The
- * workflow-run kind handler commits one JSON blob per event under
- * `runs/<runId>/events/<seq>.json` (the layout decided in the
- * pre-build interface decisions for the workflow-run repo). The
- * `subscribeKind` helper owns this layout so the substrate `subscribe`
- * stays generic and free of workflow-event vocabulary.
- */
-const RUNS_PREFIX = "runs";
-const EVENTS_DIR = "events";
+import { requireEventSeq, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "../workflow-run-kind.js";
 /**
  * Substrate envelope shape. Imported textually rather than from
  * `types.ts` so this helper has a local, validator-checked view of
@@ -24,11 +12,6 @@ const SubstrateEvent = type({
     "oldSha?": "string | null",
     newSha: "string",
 });
-/**
- * Per-event filename shape. Filenames are `<seq>.json` under
- * `runs/<runId>/events/`. `<seq>` is a non-negative decimal integer.
- */
-const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
 const KindEnvelope = type({
     type: "string",
 });
@@ -41,9 +24,12 @@ const KindEnvelope = type({
  * kinds filter against the inner `type` discriminator, and yields one
  * `{ seq, event }` entry per matching blob.
  *
- * The path layout is owned here, not in the substrate: the substrate
- * `subscribe` is a generic ref-tail primitive and knows nothing about
- * workflow-runs.
+ * The path-layout vocabulary (the `runs/`/`events/` prefixes and the
+ * `<seq>.json` filename shape) lives in the workflow-run kind handler,
+ * which is the authority for what may land under this prefix; this
+ * helper imports it rather than re-encoding it. The substrate
+ * `subscribe` it wraps is a generic ref-tail primitive and knows
+ * nothing about workflow-runs.
  *
  * Diff scope: the helper enumerates event blobs present in the new
  * commit but absent from the old commit. A commit that does not add
@@ -53,7 +39,6 @@ const KindEnvelope = type({
  */
 export async function* subscribeKind(store, principal, repoId, ref, validator, opts) {
     const kindsAllowed = new Set(opts.kinds);
-    const dir = store.getRepoDir(repoId);
     const subscribeOpts = {
         signal: opts.signal,
         from: opts.from,
@@ -67,9 +52,17 @@ export async function* subscribeKind(store, principal, repoId, ref, validator, o
         if (envelope instanceof type.errors) {
             throw new Error(`subscribe_kind_envelope_invalid: ${envelope.summary}`);
         }
-        const candidates = await collectAddedEventBlobs(dir, envelope.oldSha ?? null, envelope.newSha);
+        const newReads = await store.openCommittedReadsAtCommit(principal, repoId, envelope.newSha);
+        // A commit a concurrent GC pruned between the ref-update event and
+        // this read yields nothing; the substrate surfaces that as `null`.
+        if (newReads === null)
+            continue;
+        const oldReads = envelope.oldSha === undefined || envelope.oldSha === null
+            ? null
+            : await store.openCommittedReadsAtCommit(principal, repoId, envelope.oldSha);
+        const candidates = await collectAddedEventBlobs(newReads, oldReads);
         for (const candidate of candidates) {
-            const raw = await readBlobAtCommit(dir, envelope.newSha, candidate.blobPath);
+            const raw = await newReads.readBlobByOid(candidate.oid);
             let parsedJson;
             try {
                 parsedJson = JSON.parse(new TextDecoder().decode(raw));
@@ -94,20 +87,22 @@ export async function* subscribeKind(store, principal, repoId, ref, validator, o
     }
 }
 /**
- * Walk the `runs/<runId>/events/` subtree at `newSha` and at `oldSha`
- * (when present) and return the set of event candidates present in
- * the new commit but not in the old. Filenames that fail the
- * `<seq>.json` shape are surfaced as errors rather than silently
- * skipped — the workflow-run kind handler's validatePush is the
- * authority for what may land under this prefix, so an unexpected
- * shape here is a substrate-side invariant violation.
+ * Diff the `runs/<runId>/events/` subtree between the new and old commit
+ * reads and return the event candidates present in the new commit but
+ * not the old. `oldReads` is `null` for the ref's first commit (no prior
+ * tip) or when the prior commit is no longer in the object store, in
+ * which case every event in the new commit is treated as added.
+ * Filenames that fail the `<seq>.json` shape are surfaced as errors
+ * rather than silently skipped — the workflow-run kind handler's
+ * validatePush is the authority for what may land under this prefix, so
+ * an unexpected shape here is a substrate-side invariant violation.
  */
-async function collectAddedEventBlobs(dir, oldSha, newSha) {
-    const newSet = await enumerateEventBlobs(dir, newSha);
-    if (oldSha === null) {
+async function collectAddedEventBlobs(newReads, oldReads) {
+    const newSet = await enumerateEventBlobs(newReads);
+    if (oldReads === null) {
         return [...newSet.values()].sort(byRunThenSeq);
     }
-    const oldSet = await enumerateEventBlobs(dir, oldSha);
+    const oldSet = await enumerateEventBlobs(oldReads);
     const out = [];
     for (const [key, candidate] of newSet) {
         if (oldSet.has(key))
@@ -124,56 +119,26 @@ function byRunThenSeq(a, b) {
         return 1;
     return a.seq - b.seq;
 }
-async function enumerateEventBlobs(dir, commitOid) {
+async function enumerateEventBlobs(reads) {
     const out = new Map();
-    let commit;
-    try {
-        commit = await git.readCommit({ fs, dir, oid: commitOid });
-    }
-    catch (err) {
-        if (hasCode(err) && err.code === "NotFoundError")
-            return out;
-        throw err;
-    }
-    const runsOid = await lookupSubtree(dir, commit.commit.tree, RUNS_PREFIX);
-    if (runsOid === null)
-        return out;
-    const { tree: runs } = await git.readTree({ fs, dir, oid: runsOid });
+    const runs = await reads.listDir(WORKFLOW_RUN_RUNS_PREFIX);
     for (const runEntry of runs) {
         if (runEntry.type !== "tree")
             continue;
-        const runId = runEntry.path;
-        const eventsOid = await lookupSubtree(dir, runEntry.oid, EVENTS_DIR);
-        if (eventsOid === null)
-            continue;
-        const { tree: events } = await git.readTree({ fs, dir, oid: eventsOid });
+        const runId = runEntry.name;
+        const events = await reads.listDir(`${WORKFLOW_RUN_RUNS_PREFIX}/${runId}/${WORKFLOW_RUN_EVENTS_DIR}`);
         for (const blob of events) {
             if (blob.type !== "blob")
                 continue;
-            const match = EVENT_FILENAME_RE.exec(blob.path);
-            if (match === null) {
-                throw new Error(`subscribe_kind_unexpected_event_filename: ${RUNS_PREFIX}/${runId}/${EVENTS_DIR}/${blob.path}`);
-            }
-            const seqStr = match[1];
-            if (seqStr === undefined)
-                throw new Error("unreachable");
-            const seq = Number.parseInt(seqStr, 10);
-            const blobPath = `${RUNS_PREFIX}/${runId}/${EVENTS_DIR}/${blob.path}`;
-            out.set(`${runId}/${blob.path}`, { seq, runId, blobPath });
+            const blobPath = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}/${WORKFLOW_RUN_EVENTS_DIR}/${blob.name}`;
+            const seq = requireEventSeq(blob.name, blobPath);
+            out.set(`${runId}/${blob.name}`, {
+                seq,
+                runId,
+                blobPath,
+                oid: blob.oid,
+            });
         }
     }
     return out;
 }
-async function lookupSubtree(dir, parentTreeOid, name) {
-    const { tree } = await git.readTree({ fs, dir, oid: parentTreeOid });
-    const entry = tree.find((e) => e.path === name);
-    if (entry === undefined)
-        return null;
-    if (entry.type !== "tree")
-        return null;
-    return entry.oid;
-}
-async function readBlobAtCommit(dir, commitOid, filepath) {
-    const { blob } = await git.readBlob({ fs, dir, oid: commitOid, filepath });
-    return blob;
-}

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

@@ -80,14 +80,18 @@ export type AuthorizeFn = (principal: Principal, repoId: RepoId, ref: string, ac
  * commit under validation -- present in the prospective tree and absent from
  * the prior tree. The kind handler authoritatively detects this during its
  * validation walk and surfaces it so callers do not re-derive terminal-ness
- * by sniffing committed path shapes. `terminalEventJson` carries the raw bytes
- * of the terminal event blob so a caller can reconstruct the event without a
- * second read. A commit that carries an already-terminal run forward
- * unchanged (e.g. a later compaction commit) is NOT newly terminal and does
- * not appear here.
+ * by sniffing committed path shapes. `status` is the terminal run state the
+ * terminal event maps to, matching the `workflow_run.status` vocabulary, so a
+ * caller flips the run's row without re-parsing the event type.
+ * `terminalEventJson` carries the raw bytes of the terminal event blob so a
+ * caller that needs the full event (the supervisor's terminal-write broadcast)
+ * can reconstruct it without a second read. A commit that carries an
+ * already-terminal run forward unchanged (e.g. a later compaction commit) is
+ * NOT newly terminal and does not appear here.
  */
 export type NewlyTerminalRun = {
     runId: string;
+    status: "completed" | "failed" | "cancelled";
     terminalEventJson: string;
 };
 export type ValidatePushResult = {
@@ -315,6 +319,48 @@ export interface KindHandler {
         newSha: string;
     }) => Promise<void> | void;
 }
+/**
+ * A single child entry returned by `CommittedReads.listDir`. `name` is
+ * the entry's own path segment (no parent prefix); `oid` is its git
+ * object id; `type` is the git tree-entry kind. `oid` lets a consumer
+ * read a blob's bytes via `readBlobByOid` without re-resolving the path,
+ * and lets it prove a subtree byte-unchanged by OID equality.
+ */
+export type CommittedTreeEntry = {
+    readonly name: string;
+    readonly oid: string;
+    readonly type: "blob" | "tree" | "commit";
+};
+/**
+ * Cache-backed reads pinned to the commit a ref resolved to at the
+ * moment `openCommittedReads` was called. Every read resolves against
+ * the git object store, never the materialized working tree, so a
+ * consumer observes committed state even when the on-disk checkout lags
+ * the committed tree. The pin is fixed at open time: a concurrent commit
+ * that advances the ref afterwards does not shift the reads, so an
+ * enumerate-then-read sequence sees a single coherent snapshot.
+ *
+ * `listDir` returns the direct children of a repo-root-relative POSIX
+ * directory path (no leading or trailing slash; the empty string lists
+ * the root). A path that is absent, or resolves to a non-tree, lists as
+ * the empty array — mirroring the prior-tree closures the substrate
+ * hands a kind handler. `readBlobByOid` reads a blob's bytes by its
+ * object id; a read fault surfaces as a thrown error rather than an
+ * empty result so a consumer cannot silently degrade a missing object
+ * into an absent event.
+ */
+export type CommittedReads = {
+    listDir(relPath: string): Promise<CommittedTreeEntry[]>;
+    readBlobByOid(oid: string): Promise<Uint8Array>;
+    /**
+     * The git tree object id of the subtree at `relPath` (the empty string
+     * or "." is the commit's root tree), or `null` when `relPath` is absent
+     * or resolves to a non-tree. This is the content identity a source
+     * closure freezes for a package materialized from the tree: the sidecar
+     * re-checks the checked-out subtree against it.
+     */
+    treeOid(relPath: string): Promise<string | null>;
+};
 export interface RepoStore {
     /**
      * Bookkeeping primitive. Idempotent. Creates the repo directory
@@ -368,8 +414,16 @@ export interface RepoStore {
      * via `resolveRef` first; the substrate exposes no force-write
      * mode because silently overwriting a losing concurrent update is
      * never the right behavior.
+     *
+     * Returns the runs the received pack drove to a terminal event,
+     * aggregated across every commit it carried. The kind handler
+     * detects terminal-ness authoritatively during validation; the
+     * substrate forwards it so a caller can react (flip the run's DB
+     * row, deactivate its principal) without re-deriving terminal-ness
+     * from the committed path shape. Empty for kinds and packs that
+     * produce none.
      */
-    receivePack(principal: Principal, repoId: RepoId, ref: string, pack: Uint8Array, commitSha: string, expectedOldSha: string | null): Promise<void>;
+    receivePack(principal: Principal, repoId: RepoId, ref: string, pack: Uint8Array, commitSha: string, expectedOldSha: string | null): Promise<NewlyTerminalRun[]>;
     createPack(principal: Principal, repoId: RepoId, ref: string): Promise<{
         pack: Uint8Array;
         commitSha: string;
@@ -425,6 +479,40 @@ export interface RepoStore {
      * they reach into for ref-listing and pack negotiation.
      */
     getRepoDir(repoId: RepoId): string;
+    /**
+     * Open cache-backed reads of the committed tree at `ref`'s tip. The
+     * ref is resolved once, at call time, and every read the returned
+     * handle serves is pinned to that commit and resolves through the git
+     * object store — not the materialized working tree `getRepoDir` points
+     * at. A consumer that must observe committed state (e.g. start-time
+     * recovery reconstructing a ledger from the persisted log) reads
+     * through this rather than the working tree, which a non-atomic
+     * post-commit materialization can leave lagging on a contended
+     * filesystem.
+     *
+     * Gated under the same `resolveRef` action as `resolveRef` / `listRefs`
+     * / `subscribe`. Returns `null` when the repo does not yet exist
+     * (mirrors `listRefs`'s empty-list contract for uninitialised repos)
+     * or when `ref` does not resolve to a commit.
+     */
+    openCommittedReads(principal: Principal, repoId: RepoId, ref: string): Promise<CommittedReads | null>;
+    /**
+     * Open cache-backed reads of the committed tree at an explicit commit,
+     * the by-SHA counterpart of `openCommittedReads`. A consumer that
+     * already holds a commit id — e.g. the `newSha`/`oldSha` of a
+     * ref-update event it is diffing — reads that exact commit through
+     * this, even after the ref has advanced past it. Every read the handle
+     * serves resolves through the git object store, pinned to `commitSha`.
+     *
+     * Gated under the same `resolveRef` action as `openCommittedReads`.
+     * `commitSha` is validated at the boundary: a malformed SHA throws
+     * `commit_sha_invalid`. Returns `null` when the repo does not yet exist
+     * or when `commitSha` names no commit in the object store (a commit a
+     * concurrent GC pruned between the caller learning of it and reading
+     * it), so a caller diffing a possibly-vanished commit gets an empty
+     * view rather than a mid-walk throw.
+     */
+    openCommittedReadsAtCommit(principal: Principal, repoId: RepoId, commitSha: string): Promise<CommittedReads | null>;
     /**
      * Tail a ref's commit log. Returns an async iterator that emits
      * `{ seq, event }` entries: one per commit on the ref. `seq` is

package/dist/repo-store/user-principal-gate.d.ts

@@ -0,0 +1,26 @@
+import type { RepoAction, RepoId, Principal } from "./types.js";
+export type AuthorizeUserPrincipalArgs = {
+    principal: Principal;
+    repoId: RepoId;
+    ref: string;
+    action: RepoAction;
+    /**
+     * The resource-kind prefix the pre-resolved authz verdict must carry
+     * for this kind: the verdict's `resource` is compared against
+     * `<resourcePrefix>:<repoId.id>`.
+     */
+    resourcePrefix: string;
+};
+/**
+ * Verdict for a `user` principal performing `action` on `ref` of
+ * `repoId`, in the shape the substrate's `AuthorizeFn` contract
+ * expects. The caller dispatches on `principal.kind === "user"` first;
+ * this function narrows with `UserPrincipal` and applies the full
+ * claim/verdict cross-check.
+ */
+export declare function authorizeUserPrincipal({ principal, repoId, ref, action, resourcePrefix, }: AuthorizeUserPrincipalArgs): {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};

package/dist/repo-store/user-principal-gate.js

@@ -0,0 +1,78 @@
+// Shared authorization gate for the `user` principal variant, used by
+// every kind handler that accepts user-token-authenticated requests
+// (workflow, skill, agent-state, workflow-run).
+//
+// The route layer has already pre-resolved the grant verdict and
+// attached it as `authz`; the kind handlers do NOT re-query the grant
+// store here. This gate (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.
+//
+// Funnelling every kind through this one gate keeps the security-
+// critical claim/verdict cross-check from drifting between kinds. The
+// only per-kind input is the `resourcePrefix` the verdict's `resource`
+// must carry (`asset:<id>` for the codebase kinds, `agent-state:<id>`,
+// `workflow-run:<id>`).
+import { type } from "arktype";
+import { glob, repoActionToGrantVerb } from "@intx/hub-common";
+import { UserPrincipal } from "./types.js";
+/**
+ * Verdict for a `user` principal performing `action` on `ref` of
+ * `repoId`, in the shape the substrate's `AuthorizeFn` contract
+ * expects. The caller dispatches on `principal.kind === "user"` first;
+ * this function narrows with `UserPrincipal` and applies the full
+ * claim/verdict cross-check.
+ */
+export function authorizeUserPrincipal({ principal, repoId, ref, action, resourcePrefix, }) {
+    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 = `${resourcePrefix}:${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}`,
+    };
+}