forgeos 0.1.0-alpha.70 → 0.1.0-alpha.71

package/src/forge/agent-fabric/program-dsl.ts

@@ -1,22 +1,33 @@
+import type { WorkflowRef, WorkflowOptions, WorkflowOperation, WorkflowDefinition, WorkflowExpression, WorkflowValue, WorkflowResolved, WorkflowActivityOptions, WorkflowBody, WorkflowCollection } from "./program-api.ts";
+export type { WorkflowRef, WorkflowOptions, WorkflowOperation, WorkflowDefinition, WorkflowExpression, WorkflowValue, WorkflowResolved, WorkflowActivityOptions, WorkflowBody, WorkflowCollection } from "./program-api.ts";
 import ts from "typescript";
-import { programAssert, programValueBytes, type ProgramExpr, type ProgramOperation, type ProgramRef, type WorkflowProgramV2 } from "./program-contract.ts";
+import { programAssert, programValueBytes, type ProgramExpr, type ProgramOperation, type WorkflowProgramV2 } from "./program-contract.ts";
 
-export const PROGRAM_DSL_VERSION = "forge-workflow-dsl/1";
-const expressionNames = ["workflowInput", "item", "loopState", "output", "field", "literal", "object", "array", "eq", "and", "or", "not", "concat", "filter", "unique", "sort", "take", "length", "population", "acceptance", "acceptedCandidate", "acceptedCandidates", "outputCandidate", "candidateFromBaseline", "coverageFor", "coverageReceipt", "acceptanceWriteScope", "approvedChecksFor", "acceptanceChecks"];
-const referenceNames = ["schemaRef", "executorRef", "policyRef", "acceptanceRef", "populationRef", "recipeRef", "programRef"];
-const operationNames = ["agent", "command", "map", "branch", "loop", "compose", "gate", "repair", "subworkflow", "waitEvent", "value"];
+export const PROGRAM_DSL_VERSION = "forge-workflow-dsl/2";
+export const expressionNames = ["workflowInput", "item", "loopState", "output", "field", "literal", "object", "array", "eq", "and", "or", "not", "concat", "filter", "unique", "sort", "take", "length", "population", "acceptance", "acceptedCandidate", "acceptedCandidates", "outputCandidate", "candidateFromBaseline", "coverageFor", "coverageReceipt", "acceptanceWriteScope", "approvedChecksFor", "acceptanceChecks"];
+export const referenceNames = ["schemaRef", "executorRef", "policyRef", "acceptanceRef", "populationRef", "recipeRef", "programRef"];
+export const operationNames = ["agent", "command", "map", "branch", "loop", "compose", "gate", "repair", "subworkflow", "waitEvent", "value", "sequence", "parallel"];
 export function workflowExpression(name: string, ...args: unknown[]): ProgramExpr { return { $expr: name, args }; }
 export function workflowOperation(kind: string, id: string, options: Record<string, unknown>): ProgramOperation { return { kind, id, options }; }
-export function schemaRef(id: string, version: string): ProgramRef { return { id, version }; }
-export const executorRef = schemaRef, policyRef = schemaRef, acceptanceRef = schemaRef, populationRef = schemaRef, recipeRef = schemaRef, programRef = schemaRef;
-export const workflowInput = () => workflowExpression("workflowInput");
-export const item = () => workflowExpression("item");
-export const loopState = () => workflowExpression("loopState");
-export const output = (id: string) => workflowExpression("output", id);
-export const field = (value: unknown, key: string) => workflowExpression("field", value, key);
-export const literal = (value: unknown) => workflowExpression("literal", value);
-export const object = (value: Record<string, unknown>) => workflowExpression("object", value);
-export const array = (...values: unknown[]) => workflowExpression("array", ...values);
+export function schemaRef<T = unknown>(id: string, version: string): WorkflowRef<"schema", unknown, T> { return { id, version } as WorkflowRef<"schema", unknown, T>; }
+export const executorRef = <Input = unknown, Output = unknown>(id: string, version: string) => ({ id, version } as WorkflowRef<"executor", Input, Output>);
+export const policyRef = (id: string, version: string) => ({ id, version } as WorkflowRef<"policy">);
+export const acceptanceRef = (id: string, version: string) => ({ id, version } as WorkflowRef<"acceptance">);
+export const populationRef = (id: string, version: string) => ({ id, version } as WorkflowRef<"population">);
+export const recipeRef = (id: string, version: string) => ({ id, version } as WorkflowRef<"recipe">);
+export const programRef = <Input = unknown, Output = unknown>(id: string, version: string) => ({ id, version } as WorkflowRef<"program", Input, Output>);
+export const workflowInput = <T = unknown>() => workflowExpression("workflowInput") as WorkflowExpression<T>;
+export const item = <T = unknown>() => workflowExpression("item") as WorkflowExpression<T>;
+export const loopState = <T = unknown>() => workflowExpression("loopState") as WorkflowExpression<T>;
+export function output<T>(operation: WorkflowOperation<keyof WorkflowOptions, T>): WorkflowExpression<T>;
+export function output(id: string): WorkflowExpression;
+export function output(operation: string | WorkflowOperation): WorkflowExpression { return workflowExpression("output", typeof operation === "string" ? operation : operation.id); }
+export function field<T, K extends (unknown extends T ? string : keyof T & string)>(value: WorkflowExpression<T>, key: K): WorkflowExpression<unknown extends T ? unknown : T[K & keyof T]>;
+export function field<T, K extends keyof T & string>(value: T, key: K): WorkflowExpression<T[K]>;
+export function field(value: unknown, key: string): WorkflowExpression { return workflowExpression("field", value, key); }
+export const literal = <T>(value: T) => workflowExpression("literal", value) as WorkflowExpression<T>;
+export const object = <T extends Record<string, unknown>>(value: T) => workflowExpression("object", value) as WorkflowExpression<WorkflowResolved<T>>;
+export const array = <T extends unknown[]>(...values: T) => workflowExpression("array", ...values) as WorkflowExpression<WorkflowResolved<T>>;
 export const eq = (left: unknown, right: unknown) => workflowExpression("eq", left, right);
 export const and = (...values: unknown[]) => workflowExpression("and", ...values);
 export const or = (...values: unknown[]) => workflowExpression("or", ...values);
@@ -32,26 +43,28 @@ export const acceptance = () => workflowExpression("acceptance");
 export const acceptedCandidate = (id: string) => workflowExpression("acceptedCandidate", id);
 export const acceptedCandidates = (id: string) => workflowExpression("acceptedCandidates", id);
 export const outputCandidate = (id: string) => workflowExpression("outputCandidate", id);
-export const candidateFromBaseline = (entry: unknown) => workflowExpression("candidateFromBaseline", entry);
+export const candidateFromBaseline = (entry?: unknown) => entry === undefined ? workflowExpression("candidateFromBaseline") : workflowExpression("candidateFromBaseline", entry);
 export const coverageFor = (contract: unknown, discovered: unknown) => workflowExpression("coverageFor", contract, discovered);
 export const coverageReceipt = (id: string) => workflowExpression("coverageReceipt", id);
 export const acceptanceWriteScope = (id: string) => workflowExpression("acceptanceWriteScope", id);
 export const approvedChecksFor = (entry: unknown) => workflowExpression("approvedChecksFor", entry);
 export const acceptanceChecks = (id: string) => workflowExpression("acceptanceChecks", id);
-export const agent = (id: string, options: Record<string, unknown>) => workflowOperation("agent", id, options);
-export const command = (id: string, options: Record<string, unknown>) => workflowOperation("command", id, options);
-export const map = (id: string, options: Record<string, unknown>) => workflowOperation("map", id, options);
-export const branch = (id: string, options: Record<string, unknown>) => workflowOperation("branch", id, options);
-export const loop = (id: string, options: Record<string, unknown>) => workflowOperation("loop", id, options);
-export const compose = (id: string, options: Record<string, unknown>) => workflowOperation("compose", id, options);
-export const gate = (id: string, options: Record<string, unknown>) => workflowOperation("gate", id, options);
-export const repair = (id: string, options: Record<string, unknown>) => workflowOperation("repair", id, options);
-export const subworkflow = (id: string, options: Record<string, unknown>) => workflowOperation("subworkflow", id, options);
-export const waitEvent = (id: string, options: Record<string, unknown>) => workflowOperation("waitEvent", id, options);
-export const value = (id: string, options: Record<string, unknown>) => workflowOperation("value", id, options);
-export function defineWorkflow(program: Omit<WorkflowProgramV2, "schemaVersion">): WorkflowProgramV2 { return { schemaVersion: 2, ...program }; }
+export const agent = <Input = unknown, Output = unknown>(id: string, options: WorkflowActivityOptions<Input, Output>) => workflowOperation("agent", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"agent", Output>;
+export const command = <Input = unknown, Output = unknown>(id: string, options: WorkflowActivityOptions<Input, Output>) => workflowOperation("command", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"command", Output>;
+export const map = <T = unknown>(id: string, options: Omit<WorkflowOptions["map"], "body"> & { body: WorkflowBody<T> }) => workflowOperation("map", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"map", WorkflowCollection<T>>;
+export const branch = (id: string, options: WorkflowOptions["branch"]) => workflowOperation("branch", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"branch">;
+export const loop = (id: string, options: WorkflowOptions["loop"]) => workflowOperation("loop", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"loop">;
+export const compose = (id: string, options: WorkflowOptions["compose"]) => workflowOperation("compose", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"compose">;
+export const gate = (id: string, options: WorkflowOptions["gate"]) => workflowOperation("gate", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"gate">;
+export const repair = (id: string, options: WorkflowOptions["repair"]) => workflowOperation("repair", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"repair">;
+export const subworkflow = <Input = unknown, Output = unknown>(id: string, options: Omit<WorkflowOptions["subworkflow"], "program" | "input"> & { program: WorkflowRef<"program", Input, Output>; input: WorkflowValue<NoInfer<Input>> }) => workflowOperation("subworkflow", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"subworkflow", Output>;
+export const waitEvent = <T = unknown>(id: string, options: Omit<WorkflowOptions["waitEvent"], "schema"> & { schema: WorkflowRef<"schema", unknown, T> }) => workflowOperation("waitEvent", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"waitEvent", T>;
+export const value = <T>(id: string, options: Omit<WorkflowOptions["value"], "value"> & { value: T }) => workflowOperation("value", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"value", WorkflowResolved<T>>;
+export function defineWorkflow(program: WorkflowDefinition): WorkflowProgramV2 { return { schemaVersion: 2, operatorVersion: 2, ...program }; }
 
 /** Parse a finite AST. Never transpile, import, evaluate, or call authored JavaScript. */
+export const sequence = (id: string, options: WorkflowOptions["sequence"]) => workflowOperation("sequence", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"sequence">;
+export const parallel = (id: string, options: WorkflowOptions["parallel"]) => workflowOperation("parallel", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"parallel">;
 export function lowerWorkflowSource(source: string): WorkflowProgramV2 {
   programAssert(Buffer.byteLength(source) <= 256 * 1024, "DSL source too large");
   const file = ts.createSourceFile("workflow.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
@@ -67,7 +80,7 @@ export function lowerWorkflowSource(source: string): WorkflowProgramV2 {
     if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
     if (node.kind === ts.SyntaxKind.NullKeyword) return null;
     if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(node.operand)) return -Number(node.operand.text);
-    if (ts.isParenthesizedExpression(node)) return next(node.expression);
+    if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) return next(node.expression);
     if (ts.isIdentifier(node)) { programAssert(bindings.has(node.text), `Unknown binding ${node.text}`); programValueBytes(bindings.get(node.text), 4 * 1024 * 1024); return structuredClone(bindings.get(node.text)); }
     if (ts.isArrayLiteralExpression(node)) { programAssert(node.elements.every(element => !ts.isSpreadElement(element)), "Spread forbidden"); return evaluateList(node.elements, depth + 1); }
     if (ts.isObjectLiteralExpression(node)) {
@@ -87,10 +100,10 @@ export function lowerWorkflowSource(source: string): WorkflowProgramV2 {
       programAssert(ts.isIdentifier(node.expression), "Only DSL constructors allowed");
       const name = imports.get(node.expression.text); programAssert(name, `Unimported constructor ${node.expression.text}`);
       const args = evaluateList(node.arguments, depth + 1);
-      if (expressionNames.includes(name)) return { $expr: name, args };
+      if (expressionNames.includes(name)) { if (name === "output" && args[0] && typeof args[0] === "object" && "kind" in args[0]) args[0] = (args[0] as ProgramOperation).id; return { $expr: name, args }; }
       if (referenceNames.includes(name)) { programAssert(args.length === 2 && args.every(arg => typeof arg === "string"), "Versioned registry reference required"); return { id: args[0], version: args[1] }; }
       if (operationNames.includes(name)) { programAssert(args.length === 2 && typeof args[0] === "string" && args[1] && typeof args[1] === "object", "Operation ID and options required"); return { kind: name, id: args[0], options: args[1] }; }
-      programAssert(name === "defineWorkflow" && args.length === 1 && args[0] && typeof args[0] === "object", "Invalid workflow constructor"); return { schemaVersion: 2, ...args[0] };
+      programAssert(name === "defineWorkflow" && args.length === 1 && args[0] && typeof args[0] === "object", "Invalid workflow constructor"); return { schemaVersion: 2, operatorVersion: 2, ...args[0] };
     }
     programAssert(false, `Unsupported authored syntax ${ts.SyntaxKind[node.kind]}`);
   }
@@ -99,6 +112,7 @@ export function lowerWorkflowSource(source: string): WorkflowProgramV2 {
       programAssert(ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "forgeos/agent-fabric/workflows" && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings), "Only versioned Forge DSL named imports allowed");
       for (const element of statement.importClause.namedBindings.elements) {
         const name = element.propertyName?.text ?? element.name.text;
+        if (statement.importClause.isTypeOnly || element.isTypeOnly) { programAssert(["WorkflowOptions", "WorkflowRef", "WorkflowOperation", "WorkflowDefinition", "WorkflowExpression", "WorkflowValue", "WorkflowResolved", "WorkflowActivityOptions", "WorkflowBody", "WorkflowCollection"].includes(name), "Unknown DSL author type"); continue; }
         programAssert(["defineWorkflow", ...expressionNames, ...referenceNames, ...operationNames].includes(name) && !imports.has(element.name.text), "Unknown/duplicate DSL import"); imports.set(element.name.text, name);
       }
     } else if (ts.isVariableStatement(statement)) {

package/src/forge/agent-fabric/program-evidence.ts

@@ -0,0 +1,22 @@
+import { programAssert, programDigest, type ProgramAcceptance, type ProgramCaptureReceipt, type ProgramPopulation, type ProgramVisualCase } from "./program-contract.ts";
+import { canonicalItemKey } from "./program-structure.ts";
+
+export function validateVisualPopulation(population: ProgramPopulation): void {
+  if (!population.visualCases) return;
+  const keys = population.members.map(canonicalItemKey), cases = population.visualCases;
+  programAssert(cases.length === keys.length && new Set(cases.map(entry => canonicalItemKey(entry.itemKey))).size === keys.length && cases.every(entry => keys.includes(canonicalItemKey(entry.itemKey))), "Visual cases must cover exactly owner population");
+  const tuples = cases.map(entry => programDigest([entry.route, entry.viewport, entry.state]));
+  programAssert(new Set(tuples).size === tuples.length, "Duplicate visual route/viewport/state case");
+  for (const entry of cases) programAssert([entry.route, entry.viewport, entry.state].every(value => typeof value === "string" && value.length > 0 && value.length <= 2048) && [entry.width, entry.height].every(value => Number.isSafeInteger(value) && value > 0 && value <= 16384) && entry.width * entry.height <= 64 * 1024 * 1024, "Invalid expected visual case");
+}
+export function captureKeys(acceptance: ProgramAcceptance, phase: "item" | "final", members: string[], itemKey?: string): string[] {
+  const required = (acceptance.obligations ?? []).some(obligation => (phase === "final" || obligation.scope === "item") && obligation.requiredEvidence?.includes("capture"));
+  if (!required) return [];
+  programAssert(members.length > 0 && (phase !== "item" || itemKey && members.includes(itemKey)), "Capture obligations require an owner population");
+  return phase === "item" ? [itemKey!] : members;
+}
+export function validateVisualCapture(capture: Pick<ProgramCaptureReceipt, "itemKey" | "route" | "viewport" | "state" | "width" | "height">, cases?: ProgramVisualCase[]): void {
+  if (!cases) return;
+  const expected = cases.find(entry => canonicalItemKey(entry.itemKey) === canonicalItemKey(capture.itemKey));
+  programAssert(expected && ["route", "viewport", "state", "width", "height"].every(key => expected[key as keyof ProgramVisualCase] === capture[key as keyof typeof capture]), "Capture does not match owner visual case");
+}

package/src/forge/agent-fabric/program-image.ts

@@ -0,0 +1,15 @@
+import { programAssert } from "./program-contract.ts";
+
+/** Bounded image header validation. Pixel decoding/render acceptance belongs to the registered checker. */
+export function programImage(bytes: Uint8Array): { mime: string; width: number; height: number } {
+  const data = Buffer.from(bytes); programAssert(data.length >= 24 && data.length <= 8 * 1024 * 1024, "Invalid image byte size");
+  let mime = "", width = 0, height = 0;
+  if (data.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10])) && data.toString("ascii",12,16) === "IHDR") { mime = "image/png"; width = data.readUInt32BE(16); height = data.readUInt32BE(20); }
+  else if (data[0] === 255 && data[1] === 216) {
+    mime = "image/jpeg"; let offset = 2;
+    while (offset + 9 < data.length) { if (data[offset++] !== 255) break; const marker = data[offset++], size = data.readUInt16BE(offset); if ([192,193,194].includes(marker)) { height = data.readUInt16BE(offset+3); width = data.readUInt16BE(offset+5); break; } if (size < 2) break; offset += size; }
+  } else if (data.toString("ascii",0,4) === "RIFF" && data.toString("ascii",8,12) === "WEBP" && data.toString("ascii",12,16) === "VP8X" && data.length >= 30) {
+    mime = "image/webp"; width = 1 + data.readUIntLE(24,3); height = 1 + data.readUIntLE(27,3);
+  }
+  programAssert(width > 0 && height > 0 && width <= 16384 && height <= 16384 && width * height <= 64 * 1024 * 1024, "Unsupported/invalid image header or pixel budget"); return { mime, width, height };
+}

package/src/forge/agent-fabric/program-lock.ts

@@ -0,0 +1,50 @@
+import { link, open, readFile, unlink } from "node:fs/promises";
+import { readFileSync, unlinkSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { programAssert } from "./program-contract.ts";
+
+const code = (error: unknown) => (error as NodeJS.ErrnoException).code;
+const transient = (error: unknown) => ["ENOENT", "EEXIST", "EPERM", "EACCES", "EBUSY"].includes(code(error) ?? "");
+function dead(bytes: string): boolean {
+  const holder = JSON.parse(bytes) as { pid: number };
+  if (!Number.isSafeInteger(holder.pid) || holder.pid <= 0) return false;
+  try { process.kill(holder.pid, 0); return false; } catch (error) { return code(error) === "ESRCH"; }
+}
+/** Shared local hardlink protocol. Only a confirmed dead holder may be reclaimed. */
+export class ProgramFileLease {
+  private constructor(readonly path: string, readonly token: string, private bytes: string, private lostMessage: string) {}
+  static async acquire(path: string, options: { waitMs?: number; busyCode?: string; busyMessage?: string; lostMessage?: string } = {}): Promise<ProgramFileLease> {
+    const token = randomUUID(), bytes = JSON.stringify({ pid: process.pid, token });
+    const candidate = `${path}.${token}.candidate`, reclaim = `${path}.reclaim`, deadline = Date.now() + (options.waitMs ?? 0);
+    const handle = await open(candidate, "wx", 0o600);
+    try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+    try {
+      for (;;) {
+        try { await link(candidate, path); return new ProgramFileLease(path, token, bytes, options.lostMessage ?? "Program lock ownership changed"); }
+        catch (error) { if (!transient(error)) throw error; }
+        let reclaimed = false;
+        try {
+          const old = await readFile(path, "utf8");
+          if (dead(old)) {
+            try { const guard = readFileSync(reclaim, "utf8"); if (dead(guard) && readFileSync(reclaim, "utf8") === guard) unlinkSync(reclaim); }
+            catch (error) { if (!transient(error) && !(error instanceof SyntaxError)) throw error; }
+            let claimed = false;
+            try {
+              await link(candidate, reclaim); claimed = true;
+              if (readFileSync(path, "utf8") === old) { unlinkSync(path); reclaimed = true; }
+            } finally {
+              if (claimed) { programAssert(readFileSync(reclaim, "utf8") === bytes, "Reclaim identity changed"); unlinkSync(reclaim); }
+            }
+          }
+        } catch (error) { if (!transient(error) && !(error instanceof SyntaxError)) throw error; }
+        if (reclaimed) continue;
+        programAssert(Date.now() < deadline, options.busyMessage ?? "Program lock busy", options.busyCode ?? "AF_PROGRAM_CONFLICT");
+        await new Promise(resolve => setTimeout(resolve, 20));
+      }
+    } finally { await unlink(candidate).catch(() => {}); }
+  }
+  async assert(): Promise<void> { programAssert(await readFile(this.path, "utf8") === this.bytes, this.lostMessage); }
+  async close(): Promise<void> {
+    programAssert(readFileSync(this.path, "utf8") === this.bytes, this.lostMessage); unlinkSync(this.path);
+  }
+}

package/src/forge/agent-fabric/program-owner.ts

@@ -0,0 +1,16 @@
+import { join } from "node:path";
+import { ProgramFileLease } from "./program-lock.ts";
+
+/** Owner and transactions use the same crash-recoverable admission protocol. */
+export class ProgramOwnerLease {
+  private constructor(private lease: ProgramFileLease) {}
+  get path(): string { return this.lease.path; }
+  get epoch(): string { return this.lease.token; }
+  static async acquire(directory: string): Promise<ProgramOwnerLease> {
+    return new ProgramOwnerLease(await ProgramFileLease.acquire(join(directory, "owner.lock"), {
+      busyCode: "AF_PROGRAM_OWNER_BUSY", busyMessage: "Another program owner is active or reclaiming", lostMessage: "Owner admission lease lost",
+    }));
+  }
+  async assert(): Promise<void> { await this.lease.assert(); }
+  async close(): Promise<void> { await this.lease.close(); }
+}

package/src/forge/agent-fabric/program-scheduler.ts

@@ -0,0 +1,38 @@
+import { programAssert } from "./program-contract.ts";
+
+export interface ActivityScope { id: string; limit: number }
+interface Ticket { runId: string; runLimit: number; scopes: ActivityScope[]; resolve: (release: () => void) => void; reject: (error: Error) => void; signal: AbortSignal; abort: () => void }
+/** Round robin between eligible runs; parent controls never hold activity capacity. */
+export class ProgramActivityScheduler {
+  private tickets: Ticket[] = [];
+  private active = new Map<string, number>();
+  private scopes = new Map<string, number>();
+  private count = 0;
+  private lastRun = "";
+  constructor(readonly ownerLimit = 4) { programAssert(Number.isSafeInteger(ownerLimit) && ownerLimit > 0 && ownerLimit <= 32, "Invalid owner capacity"); }
+  restore(runId: string, scopes: ActivityScope[]): () => void {
+    this.count++; this.active.set(runId, (this.active.get(runId) ?? 0) + 1);
+    for (const scope of scopes) this.scopes.set(scope.id, (this.scopes.get(scope.id) ?? 0) + 1);
+    let released = false;
+    return () => { if (released) return; released = true; this.count--; this.active.set(runId, this.active.get(runId)! - 1); for (const scope of scopes) this.scopes.set(scope.id, this.scopes.get(scope.id)! - 1); this.drain(); };
+  }
+  acquire(runId: string, runLimit: number, scopes: ActivityScope[], signal: AbortSignal): Promise<() => void> {
+    return new Promise((resolve, reject) => {
+      const ticket: Ticket = { runId, runLimit, scopes, resolve, reject, signal, abort: () => { this.tickets = this.tickets.filter(entry => entry !== ticket); reject(new Error("Activity admission canceled")); this.drain(); } };
+      if (signal.aborted) { ticket.abort(); return; }
+      signal.addEventListener("abort", ticket.abort, { once: true }); this.tickets.push(ticket); this.drain();
+    });
+  }
+  private drain(): void {
+    while (this.count < this.ownerLimit) {
+      const eligible = this.tickets.filter(ticket => !ticket.signal.aborted && (this.active.get(ticket.runId) ?? 0) < ticket.runLimit && ticket.scopes.every(scope => (this.scopes.get(scope.id) ?? 0) < scope.limit));
+      const ticket = eligible.find(entry => entry.runId !== this.lastRun) ?? eligible[0]; if (!ticket) return;
+      this.tickets.splice(this.tickets.indexOf(ticket), 1); ticket.signal.removeEventListener("abort", ticket.abort);
+      this.lastRun = ticket.runId; this.count++; this.active.set(ticket.runId, (this.active.get(ticket.runId) ?? 0) + 1);
+      for (const scope of ticket.scopes) this.scopes.set(scope.id, (this.scopes.get(scope.id) ?? 0) + 1);
+      let released = false;
+      ticket.resolve(() => { if (released) return; released = true; this.count--; this.active.set(ticket.runId, this.active.get(ticket.runId)! - 1); for (const scope of ticket.scopes) this.scopes.set(scope.id, this.scopes.get(scope.id)! - 1); this.drain(); });
+    }
+  }
+  snapshot(): { active: number; queued: number; ownerLimit: number } { return { active: this.count, queued: this.tickets.length, ownerLimit: this.ownerLimit }; }
+}