forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/forge/agent-fabric/attached-task-service.ts

@@ -0,0 +1,127 @@
+import { randomUUID } from "node:crypto";
+import { AttachedTaskStore } from "./attached-task-store.ts";
+import { attachedDigest, attachedHead, captureAttachedSnapshot } from "./attached-snapshot.ts";
+import { attachedReadiness } from "./readiness.ts";
+import { stableStringify } from "./canonical.ts";
+import { attachedFail, attachedObject, attachedText, attachedId, attachedList, attachedUnique, attachedScope, type AttachedTaskState } from "./attached-task-contract.ts";
+import { applyWorkflowTaskAction, readWorkflowTaskAction } from "./workflow-task-actions.ts";
+
+const mutationFields = ["taskId", "requestId", "expectedVersion"];
+const fields: Record<string, string[]> = {
+  "attached-propose": ["requestId", "goal", "criteria", "scope", "requiredChecks"],
+  "attached-status": ["taskId"], "attached-context": ["taskId"],
+  "attached-attach": [...mutationFields, "sessionId", "agentId"],
+  "attached-assign": [...mutationFields, "assignmentId", "role", "sessionId", "agentId"],
+  "attached-attempt": [...mutationFields, "attemptId", "assignmentId", "status"],
+  "attached-prepare-review": [...mutationFields, "reviewerAttemptId", "implementationAttemptId"],
+  "attached-submit-review": [...mutationFields, "reviewToken", "snapshotDigest", "reviewerAttemptId", "implementationAttemptId", "verdict", "findings"],
+  "attached-record-verification": [...mutationFields, "checkId", "snapshotDigest", "outcome", "command", "summary"],
+  "attached-cover": [...mutationFields, "criterionId", "snapshotDigest", "evidence"],
+};
+function oneOf<T extends string>(value: unknown, choices: readonly T[], label: string): T {
+  if (typeof value !== "string" || !choices.includes(value as T)) attachedFail("AF_ATTACHED_INPUT", `Invalid ${label}`);
+  return value as T;
+}
+function digest(value: unknown): string { const text = attachedText(value, "snapshotDigest", 64); if (!/^[0-9a-f]{64}$/u.test(text)) attachedFail("AF_ATTACHED_INPUT", "Invalid snapshotDigest"); return text; }
+
+/** Native Codex reports are attributed evidence, never execution proof. */
+export class AttachedTaskService {
+  private closed = false;
+  private constructor(readonly root: string, private readonly store: AttachedTaskStore) {}
+  static async open(root: string): Promise<AttachedTaskService> { const store = await AttachedTaskStore.open(root); await attachedHead(store.root); return new AttachedTaskService(store.root, store); }
+  async close(): Promise<void> { this.closed = true; }
+  private async response(state: AttachedTaskState, extra: Record<string, unknown> = {}, fullState = true): Promise<Record<string, unknown>> {
+    const snapshot = await captureAttachedSnapshot(this.root, state.scope, state.baseHead);
+    if (extra.resume) (extra.resume as Record<string, unknown>).next = state.workflow ? readWorkflowTaskAction(state, "workflow-next", snapshot.digest) : null;
+    if (extra.workflowNext) { delete extra.workflowNext; extra.workflowResult = readWorkflowTaskAction(state, "workflow-next", snapshot.digest); }
+    return { taskId: state.taskId, version: state.version, ...(fullState ? { state } : {}), readiness: attachedReadiness(state, snapshot), ...extra };
+  }
+  async execute(action: string, input: unknown): Promise<unknown> {
+    if (this.closed) attachedFail("AF_ATTACHED_CLOSED", "Service is closed");
+    const workflow = action.startsWith("workflow-");
+    if (!fields[action] && !workflow) attachedFail("AF_ATTACHED_ACTION", `Unknown attached action: ${action}`);
+    if (!input || typeof input !== "object") attachedFail("AF_ATTACHED_INPUT", "Expected an object");
+    const body = attachedObject(input, workflow ? Object.keys(input) : fields[action]!);
+    if (action === "attached-status" || action === "attached-context" || action === "workflow-next") {
+      if (action === "workflow-next") attachedObject(body, ["taskId"]);
+      const state = await this.store.read(attachedId(body.taskId, "taskId"));
+      return this.response(state, action === "attached-context" ? { resume: { goal: state.goal, criteria: state.criteria, assignments: state.assignments, attempts: state.attempts } } : action === "workflow-next" ? { workflowNext: true } : {});
+    }
+    const requestId = attachedId(body.requestId, "requestId");
+    const proposal = action === "attached-propose";
+    const taskId = proposal ? `attached-${attachedDigest(requestId).slice(0, 32)}` : attachedId(body.taskId, "taskId");
+    const expectedVersion = proposal ? undefined : body.expectedVersion;
+    if (!proposal && (!Number.isSafeInteger(expectedVersion) || (expectedVersion as number) < 1)) attachedFail("AF_ATTACHED_INPUT", "expectedVersion must be a positive integer");
+    const fingerprint = attachedDigest(stableStringify({ action, body }));
+    return this.store.mutate(taskId, requestId, fingerprint, expectedVersion as number | undefined, async (old) => {
+      if (proposal) {
+        if (old) attachedFail("AF_ATTACHED_EXISTS", "Task already exists");
+        const criteria = attachedList(body.criteria, "criteria").map((item) => { const criterion = attachedObject(item, ["criterionId", "description"]); return { criterionId: attachedId(criterion.criterionId, "criterionId"), description: attachedText(criterion.description, "description") }; });
+        if (!criteria.length) attachedFail("AF_ATTACHED_INPUT", "At least one acceptance criterion is required");
+        attachedUnique(criteria.map((item) => item.criterionId), "criteria");
+        const requiredChecks = attachedList(body.requiredChecks, "requiredChecks").map((item) => attachedId(item, "checkId")); attachedUnique(requiredChecks, "checks");
+        const state: AttachedTaskState = { schemaVersion: 1, taskId, version: 1, goal: attachedText(body.goal, "goal"), criteria, scope: attachedScope(body.scope), baseHead: await attachedHead(this.root), requiredChecks, sessions: [], assignments: [], attempts: [], preparedReviews: [], verifications: [], coverage: [] };
+        return { state, response: await this.response(state, {}, false) };
+      }
+      if (!old) attachedFail("AF_ATTACHED_NOT_FOUND", "Task does not exist");
+      let state = structuredClone(old);
+      let extra: Record<string, unknown> = {};
+      if (workflow) { const snapshot = await captureAttachedSnapshot(this.root, state.scope, state.baseHead); const result = applyWorkflowTaskAction(state, action, body, snapshot.digest); state = result.state; if (result.result !== undefined) { const { state: _workflowState, ...schedule } = result.result as Record<string, unknown>; extra = { workflowResult: schedule }; } }
+      else extra = await this.apply(state, action, body);
+      state.version = old.version + 1;
+      return { state, response: await this.response(state, extra, false) };
+    });
+  }
+  private async apply(state: AttachedTaskState, action: string, body: Record<string, unknown>): Promise<Record<string, unknown>> {
+    if (action === "attached-attach") {
+      const session = { sessionId: attachedId(body.sessionId, "sessionId"), agentId: attachedId(body.agentId, "agentId") };
+      if (!state.sessions.some((item) => item.sessionId === session.sessionId && item.agentId === session.agentId)) state.sessions.push(session);
+    } else if (action === "attached-assign") {
+      const assignment = { assignmentId: attachedId(body.assignmentId, "assignmentId"), role: oneOf(body.role, ["implementer", "reviewer"] as const, "role"), sessionId: attachedId(body.sessionId, "sessionId"), agentId: attachedId(body.agentId, "agentId") };
+      if (!state.sessions.some((item) => item.sessionId === assignment.sessionId && item.agentId === assignment.agentId)) attachedFail("AF_ATTACHED_SESSION", "Attach the agent session before assigning work");
+      if (state.assignments.some((item) => item.assignmentId === assignment.assignmentId)) attachedFail("AF_ATTACHED_ASSIGNMENT", "assignmentId already exists");
+      state.assignments.push(assignment);
+    } else if (action === "attached-attempt") {
+      const attemptId = attachedId(body.attemptId, "attemptId"), assignmentId = attachedId(body.assignmentId, "assignmentId");
+      const status = oneOf(body.status, ["running", "succeeded", "failed", "uncertain"] as const, "status");
+      if (!state.assignments.some((item) => item.assignmentId === assignmentId)) attachedFail("AF_ATTACHED_ASSIGNMENT", "Unknown assignment");
+      const attempt = state.attempts.find((item) => item.attemptId === attemptId);
+      if (attempt) {
+        if (attempt.assignmentId !== assignmentId || attempt.status === "succeeded" || attempt.status === "failed") attachedFail("AF_ATTACHED_ATTEMPT", "Terminal attempts are immutable; create a new attempt");
+        attempt.status = status;
+      } else { if (status !== "running") attachedFail("AF_ATTACHED_ATTEMPT", "New attempts must start running"); state.attempts.push({ attemptId, assignmentId, status }); }
+    } else if (action === "attached-prepare-review" || action === "attached-submit-review") {
+      const reviewerAttemptId = attachedId(body.reviewerAttemptId, "reviewerAttemptId"), implementationAttemptId = attachedId(body.implementationAttemptId, "implementationAttemptId");
+      const implementation = state.attempts.find((item) => item.attemptId === implementationAttemptId), reviewer = state.attempts.find((item) => item.attemptId === reviewerAttemptId);
+      const implementerAssignment = state.assignments.find((item) => item.assignmentId === implementation?.assignmentId), reviewerAssignment = state.assignments.find((item) => item.assignmentId === reviewer?.assignmentId);
+      if (!implementation || implementation.status !== "succeeded" || !reviewer || reviewer.status !== "running" || implementerAssignment?.role !== "implementer" || reviewerAssignment?.role !== "reviewer") attachedFail("AF_ATTACHED_REVIEW", "Review requires a succeeded implementation and running reviewer attempt");
+      if (implementerAssignment.agentId === reviewerAssignment.agentId) attachedFail("AF_ATTACHED_SELF_REVIEW", "Reviewer must be a distinct agent");
+      const snapshot = await captureAttachedSnapshot(this.root, state.scope, state.baseHead);
+      if (action === "attached-prepare-review") {
+        const prepared = { reviewToken: randomUUID(), snapshot, reviewerAttemptId, implementationAttemptId }; state.preparedReviews.push(prepared); return prepared;
+      }
+      const reviewToken = attachedText(body.reviewToken, "reviewToken", 128);
+      const prepared = state.preparedReviews.find((item) => item.reviewToken === reviewToken);
+      if (!prepared || prepared.reviewerAttemptId !== reviewerAttemptId || prepared.implementationAttemptId !== implementationAttemptId || prepared.snapshot.digest !== digest(body.snapshotDigest) || snapshot.digest !== body.snapshotDigest) attachedFail("AF_ATTACHED_STALE_REVIEW", "Review token or snapshot is no longer current");
+      const findings = attachedList(body.findings, "findings").map((item) => { const finding = attachedObject(item, ["findingId", "description", "resolved"]); if (typeof finding.resolved !== "boolean") attachedFail("AF_ATTACHED_INPUT", "resolved must be boolean"); return { findingId: attachedId(finding.findingId, "findingId"), description: attachedText(finding.description, "description"), resolved: finding.resolved }; });
+      attachedUnique(findings.map((item) => item.findingId), "findings");
+      state.review = { reviewToken, snapshotDigest: snapshot.digest, reviewerAttemptId, implementationAttemptId, verdict: oneOf(body.verdict, ["approved", "changes_requested"] as const, "verdict"), findings, provenance: "agent_reported" };
+      reviewer.status = "succeeded";
+    } else if (action === "attached-record-verification" || action === "attached-cover") {
+      const snapshot = await captureAttachedSnapshot(this.root, state.scope, state.baseHead);
+      if (digest(body.snapshotDigest) !== snapshot.digest) attachedFail("AF_ATTACHED_STALE_EVIDENCE", "Evidence applies to an obsolete snapshot");
+      if (action === "attached-record-verification") {
+        const checkId = attachedId(body.checkId, "checkId");
+        if (!state.requiredChecks.includes(checkId)) attachedFail("AF_ATTACHED_CHECK", "Unknown required check");
+        state.verifications = state.verifications.filter((item) => item.checkId !== checkId || item.snapshotDigest !== snapshot.digest);
+        state.verifications.push({ checkId, snapshotDigest: snapshot.digest, outcome: oneOf(body.outcome, ["passed", "failed", "inconclusive"] as const, "outcome"), command: attachedText(body.command, "command"), summary: attachedText(body.summary, "summary"), provenance: "agent_reported" });
+      } else {
+        const criterionId = attachedId(body.criterionId, "criterionId");
+        if (!state.criteria.some((item) => item.criterionId === criterionId)) attachedFail("AF_ATTACHED_CRITERION", "Unknown criterion");
+        state.coverage = state.coverage.filter((item) => item.criterionId !== criterionId || item.snapshotDigest !== snapshot.digest);
+        state.coverage.push({ criterionId, snapshotDigest: snapshot.digest, evidence: attachedText(body.evidence, "evidence"), provenance: "agent_reported" });
+      }
+    } else attachedFail("AF_ATTACHED_ACTION", "Unsupported action");
+    return {};
+  }
+}

package/src/forge/agent-fabric/attached-task-store.ts

@@ -0,0 +1,109 @@
+import { mkdir, open, readFile, rename, unlink, link, lstat, realpath } from "node:fs/promises";
+import { readFileSync, unlinkSync, lstatSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { attachedFail, attachedId, validateAttachedTaskState, type AttachedTaskState } from "./attached-task-contract.ts";
+import { assertAttachedSafePath, attachedDigest } from "./attached-snapshot.ts";
+import { stableStringify } from "./canonical.ts";
+
+interface Receipt { requestId: string; fingerprint: string; response: unknown }
+interface RecordFile { state: AttachedTaskState; receipts: Receipt[] }
+const missing = (error: unknown) => (error as NodeJS.ErrnoException).code === "ENOENT";
+function alive(pid: number): boolean { try { process.kill(pid, 0); return true; } catch (error) { return (error as NodeJS.ErrnoException).code !== "ESRCH"; } }
+function reclaimDeadGuard(path: string): void {
+  try {
+    if (!lstatSync(path).isFile()) attachedFail("AF_ATTACHED_LOCK", "Unsupported reclaim guard");
+    const raw = readFileSync(path, "utf8"); const owner = JSON.parse(raw);
+    if (Number.isSafeInteger(owner.pid) && owner.pid > 0 && !alive(owner.pid) && readFileSync(path, "utf8") === raw) unlinkSync(path);
+  } catch (error) { if (!missing(error) && !(error instanceof SyntaxError)) throw error; }
+}
+
+/** One atomic state+receipt commit; a published hardlink lock serializes processes. */
+export class AttachedTaskStore {
+  private constructor(readonly root: string, readonly directory: string) {}
+  static async open(root: string): Promise<AttachedTaskStore> {
+    root = await realpath(root);
+    const directory = join(root, ".forge", "local", "agent-fabric", "attached-tasks");
+    await assertAttachedSafePath(root, directory);
+    await mkdir(directory, { recursive: true });
+    await assertAttachedSafePath(root, directory);
+    return new AttachedTaskStore(root, directory);
+  }
+  private path(taskId: string): string { return join(this.directory, `${attachedId(taskId, "taskId")}.json`); }
+  async read(taskId: string): Promise<AttachedTaskState> {
+    const record = await this.load(taskId);
+    if (!record) attachedFail("AF_ATTACHED_NOT_FOUND", "Task does not exist");
+    return record.state;
+  }
+  private async load(taskId: string): Promise<RecordFile | undefined> {
+    const path = this.path(taskId);
+    await assertAttachedSafePath(this.root, path);
+    try {
+      if ((await lstat(path)).size > 16 * 1024 * 1024) attachedFail("AF_ATTACHED_STORE", "Task record exceeds limit");
+      const envelope = JSON.parse(await readFile(path, "utf8")) as { record: RecordFile; digest: string };
+      if (!envelope.record || envelope.digest !== attachedDigest(stableStringify(envelope.record))) attachedFail("AF_ATTACHED_STORE", "Task record integrity check failed");
+      const record = envelope.record;
+      if (record.state?.schemaVersion !== 1 || record.state.taskId !== taskId || !Array.isArray(record.receipts)) attachedFail("AF_ATTACHED_STORE", "Invalid task record");
+      validateAttachedTaskState(record.state);
+      for (const receipt of record.receipts) { attachedId(receipt.requestId, "requestId"); if (!/^[0-9a-f]{64}$/u.test(receipt.fingerprint)) attachedFail("AF_ATTACHED_STORE", "Invalid receipt"); }
+      return record;
+    } catch (error) { if (missing(error)) return undefined; throw error; }
+  }
+  private async lock(taskId: string): Promise<() => Promise<void>> {
+    const lock = `${this.path(taskId)}.lock`;
+    const token = randomUUID();
+    const candidate = `${lock}.${token}.candidate`;
+    const claim = `${lock}.reclaim`;
+    const ownerBytes = JSON.stringify({ pid: process.pid, token });
+    const deadline = Date.now() + 10000;
+    await assertAttachedSafePath(this.root, candidate);
+    const handle = await open(candidate, "wx", 0o600);
+    try { await handle.writeFile(ownerBytes); await handle.sync(); } finally { await handle.close(); }
+    try {
+      while (true) {
+        await assertAttachedSafePath(this.root, lock);
+        try {
+          await link(candidate, lock);
+          return async () => { await assertAttachedSafePath(this.root, lock); if (await readFile(lock, "utf8") !== ownerBytes) attachedFail("AF_ATTACHED_LOCK", "Lock ownership changed"); await unlink(lock); };
+        } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+        try {
+          if (!(await lstat(lock)).isFile()) attachedFail("AF_ATTACHED_LOCK", "Unsupported old or malformed lock; inspect before removing");
+          const raw = await readFile(lock, "utf8"); const previous = JSON.parse(raw);
+          if (Number.isSafeInteger(previous.pid) && previous.pid > 0 && !alive(previous.pid)) {
+            await assertAttachedSafePath(this.root, claim);
+            reclaimDeadGuard(claim);
+            let claimed = false;
+            try {
+              await link(candidate, claim); claimed = true;
+              if (readFileSync(lock, "utf8") === raw) unlinkSync(lock);
+            } catch (error) { if (!missing(error) && (error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+            finally { if (claimed) await unlink(claim).catch(() => {}); }
+          }
+        } catch (error) { if (!missing(error) && !(error instanceof SyntaxError)) throw error; }
+        if (Date.now() >= deadline) attachedFail("AF_ATTACHED_LOCK_BUSY", "Task is locked; retry after its owner exits");
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      }
+    } finally { await unlink(candidate).catch(() => {}); }
+  }
+  async mutate(taskId: string, requestId: string, fingerprint: string, expectedVersion: number | undefined, apply: (state: AttachedTaskState | undefined) => Promise<{ state: AttachedTaskState; response: unknown }>): Promise<unknown> {
+    const release = await this.lock(taskId);
+    try {
+      const old = await this.load(taskId);
+      const receipt = old?.receipts.find((item) => item.requestId === requestId);
+      if (receipt) { if (receipt.fingerprint !== fingerprint) attachedFail("AF_ATTACHED_REQUEST_CONFLICT", "requestId was already used with different input"); return receipt.response; }
+      if (old && old.state.version !== expectedVersion) attachedFail("AF_ATTACHED_VERSION_CONFLICT", `Expected version ${old.state.version}`);
+      if (!old && expectedVersion !== undefined) attachedFail("AF_ATTACHED_NOT_FOUND", "Task does not exist");
+      const result = await apply(old?.state);
+      const record: RecordFile = { state: result.state, receipts: [...(old?.receipts ?? []), { requestId, fingerprint, response: result.response }] };
+      validateAttachedTaskState(record.state);
+      const data = stableStringify({ record, digest: attachedDigest(stableStringify(record)) });
+      if (Buffer.byteLength(data) > 16 * 1024 * 1024) attachedFail("AF_ATTACHED_STORE", "Task record exceeds limit");
+      const temp = `${this.path(taskId)}.${randomUUID()}.tmp`;
+      await assertAttachedSafePath(this.root, temp);
+      const handle = await open(temp, "wx", 0o600);
+      try { await handle.writeFile(data); await handle.sync(); } finally { await handle.close(); }
+      try { await assertAttachedSafePath(this.root, this.path(taskId)); await rename(temp, this.path(taskId)); } finally { await unlink(temp).catch(() => {}); }
+      return result.response;
+    } finally { await release(); }
+  }
+}

package/src/forge/agent-fabric/authority.ts

@@ -0,0 +1,298 @@
+import { getOwn, setOwn } from "./dictionary.ts";
+import { AgentFabricError } from "./errors.ts";
+import { ResourceLedger } from "./resource-ledger.ts";
+import type {
+  AuthorityResolution,
+  ControlState,
+  DerivedGrantRequest,
+  EffectClass,
+  ExecutionGrant,
+  OwnerAuthorization,
+} from "./types.ts";
+
+function isSubset<T>(child: readonly T[], parent: readonly T[]): boolean {
+  const allowed = new Set(parent);
+  return child.every((value) => allowed.has(value));
+}
+
+function reject(...reasonCodes: string[]): AuthorityResolution {
+  return { outcome: "rejected", reasonCodes, limitations: [] };
+}
+
+export function rootGrantAuthorizationViolations(
+  authorization: OwnerAuthorization,
+  grant: ExecutionGrant,
+): readonly string[] {
+  const violations: string[] = [];
+  if (grant.parentGrantId !== null) violations.push("root_grant_has_parent");
+  if (grant.rootAuthorizationId !== authorization.authorizationId) {
+    violations.push("root_authorization_mismatch");
+  }
+  if (authorization.rootExecutionId.length === 0) violations.push("authorization_missing_execution");
+  if (!authorization.subjectIds.includes(grant.subjectId)) violations.push("subject_not_authorized");
+  if (!isSubset(grant.capabilities, authorization.capabilities)) violations.push("capability_scope_expanded");
+  if (!isSubset(grant.sourceIds, authorization.sourceIds)) violations.push("source_scope_expanded");
+  if (!isSubset(grant.targetIds, authorization.targetIds)) violations.push("target_scope_expanded");
+  if (!isSubset<EffectClass>(grant.effectClasses, authorization.effectClasses)) {
+    violations.push("effect_scope_expanded");
+  }
+  if (grant.notBefore < authorization.notBefore || grant.expiresAt > authorization.expiresAt) {
+    violations.push("time_scope_expanded");
+  }
+  if (grant.expiresAt <= grant.notBefore) violations.push("invalid_time_window");
+  if (grant.maximumAttempts <= 0 || grant.maximumAttempts > authorization.maximumAttempts) {
+    violations.push("attempt_limit_expanded");
+  }
+  if (
+    grant.delegationDepthRemaining < 0 ||
+    grant.delegationDepthRemaining > authorization.maximumDelegationDepth
+  ) {
+    violations.push("delegation_depth_expanded");
+  }
+  for (const [resource, amount] of Object.entries(grant.resourceCeilings)) {
+    const ceiling = getOwn(authorization.resourceCeilings, resource);
+    if (!Number.isFinite(amount) || amount <= 0 || ceiling === undefined || amount > ceiling) {
+      violations.push(`resource_ceiling_expanded:${resource}`);
+    }
+  }
+  return violations;
+}
+
+export function assertRootGrantAuthorized(
+  authorization: OwnerAuthorization,
+  grant: ExecutionGrant,
+): void {
+  const violations = rootGrantAuthorizationViolations(authorization, grant);
+  if (violations.length > 0) {
+    throw new AgentFabricError(
+      "AF_GRANT_REJECTED",
+      `Root grant ${grant.grantId} exceeds authorization ${authorization.authorizationId}`,
+      { violations },
+    );
+  }
+}
+
+export function grantAttenuationViolations(
+  parent: ExecutionGrant,
+  child: ExecutionGrant,
+): readonly string[] {
+  const violations: string[] = [];
+  if (child.parentGrantId !== parent.grantId) violations.push("parent_grant_mismatch");
+  if (child.rootAuthorizationId !== parent.rootAuthorizationId) {
+    violations.push("root_authorization_changed");
+  }
+  if (!child.reservationId) violations.push("derived_grant_missing_reservation");
+  if (!isSubset(child.capabilities, parent.capabilities)) violations.push("capability_scope_expanded");
+  if (!isSubset(child.sourceIds, parent.sourceIds)) violations.push("source_scope_expanded");
+  if (!isSubset(child.targetIds, parent.targetIds)) violations.push("target_scope_expanded");
+  if (!isSubset<EffectClass>(child.effectClasses, parent.effectClasses)) {
+    violations.push("effect_scope_expanded");
+  }
+  if (child.notBefore < parent.notBefore || child.expiresAt > parent.expiresAt) {
+    violations.push("time_scope_expanded");
+  }
+  if (child.expiresAt <= child.notBefore) violations.push("invalid_time_window");
+  if (child.maximumAttempts <= 0 || child.maximumAttempts > parent.maximumAttempts) {
+    violations.push("attempt_limit_expanded");
+  }
+  if (
+    child.delegationDepthRemaining < 0 ||
+    child.delegationDepthRemaining >= parent.delegationDepthRemaining
+  ) {
+    violations.push("delegation_depth_not_attenuated");
+  }
+  for (const [resource, amount] of Object.entries(child.resourceCeilings)) {
+    const ceiling = getOwn(parent.resourceCeilings, resource);
+    if (!Number.isFinite(amount) || amount <= 0 || ceiling === undefined || amount > ceiling) {
+      violations.push(`resource_ceiling_expanded:${resource}`);
+    }
+  }
+  return violations;
+}
+
+export function assertGrantAttenuated(
+  parent: ExecutionGrant,
+  child: ExecutionGrant,
+): void {
+  const violations = grantAttenuationViolations(parent, child);
+  if (violations.length > 0) {
+    throw new AgentFabricError(
+      "AF_GRANT_REJECTED",
+      `Derived grant ${child.grantId} is not attenuated from ${parent.grantId}`,
+      { violations },
+    );
+  }
+}
+
+export function deriveExecutionGrant(
+  parent: ExecutionGrant,
+  request: DerivedGrantRequest,
+  ledger: ResourceLedger,
+  now: number,
+): AuthorityResolution {
+  if (now < parent.notBefore || now >= parent.expiresAt) {
+    return reject("parent_grant_not_current");
+  }
+
+  const aggregatedResourceRequests = Object.entries(
+    request.resourceRequests.reduce<Record<string, number>>((totals, resourceRequest) => {
+      setOwn(totals, resourceRequest.resource, (getOwn(totals, resourceRequest.resource) ?? 0) + resourceRequest.amount);
+      return totals;
+    }, {}),
+  ).map(([resource, amount]) => ({ resource, amount }));
+
+  const candidate: ExecutionGrant = {
+    grantId: request.grantId,
+    rootAuthorizationId: parent.rootAuthorizationId,
+    subjectId: request.subjectId,
+    parentGrantId: parent.grantId,
+    capabilities: [...request.capabilities],
+    sourceIds: [...request.sourceIds],
+    targetIds: [...request.targetIds],
+    effectClasses: [...request.effectClasses],
+    notBefore: request.notBefore,
+    expiresAt: request.expiresAt,
+    maximumAttempts: request.maximumAttempts,
+    delegationDepthRemaining: request.delegationDepthRemaining,
+    resourceCeilings: Object.fromEntries(
+      aggregatedResourceRequests.map((item) => [item.resource, item.amount]),
+    ),
+    reservationId: request.reservationId,
+  };
+  const violations = grantAttenuationViolations(parent, candidate);
+  if (violations.length > 0) return reject(...violations);
+
+  try {
+    const reserved = ledger.reserve(
+      request.reservationId,
+      parent.grantId,
+      aggregatedResourceRequests,
+      parent.resourceCeilings,
+    );
+    return {
+      outcome: "allowed",
+      reasonCodes: [],
+      limitations: [],
+      grant: {
+        ...candidate,
+        resourceCeilings: Object.fromEntries(
+          reserved.requests.map((item) => [item.resource, item.amount]),
+        ),
+      },
+    };
+  } catch (error) {
+    if (error instanceof AgentFabricError) {
+      return reject(error.code.toLowerCase());
+    }
+    return { outcome: "unknown", reasonCodes: ["resource_reservation_unknown"], limitations: [] };
+  }
+}
+
+export function assertAuthorizationCurrent(
+  authorization: OwnerAuthorization,
+  now: number,
+  revokedReason?: string,
+): void {
+  if (revokedReason) {
+    throw new AgentFabricError(
+      "AF_GRANT_REJECTED",
+      `Owner authorization ${authorization.authorizationId} is revoked`,
+      { revokedReason },
+    );
+  }
+  if (now < authorization.notBefore || now >= authorization.expiresAt) {
+    throw new AgentFabricError(
+      "AF_GRANT_REJECTED",
+      `Owner authorization ${authorization.authorizationId} is outside its validity window`,
+    );
+  }
+}
+
+export function assertGrantCurrent(
+  grant: ExecutionGrant,
+  now: number,
+  revokedReason?: string,
+): void {
+  if (revokedReason) {
+    throw new AgentFabricError(
+      "AF_GRANT_REJECTED",
+      `Grant ${grant.grantId} is revoked`,
+      { revokedReason },
+    );
+  }
+  if (now < grant.notBefore || now >= grant.expiresAt) {
+    throw new AgentFabricError(
+      "AF_GRANT_REJECTED",
+      `Grant ${grant.grantId} is outside its validity window`,
+    );
+  }
+}
+
+export function assertGrantLineageCurrent(
+  state: Pick<
+    ControlState,
+    | "authorizations"
+    | "revokedAuthorizations"
+    | "grants"
+    | "revokedGrants"
+    | "resourceReservations"
+  >,
+  grantId: string,
+  now: number,
+): void {
+  const seen = new Set<string>();
+  const selected = getOwn(state.grants, grantId);
+  if (!selected) throw new AgentFabricError("AF_NOT_FOUND", `Unknown grant: ${grantId}`);
+  let current: ExecutionGrant = selected;
+
+  while (true) {
+    if (seen.has(current.grantId)) {
+      throw new AgentFabricError("AF_GRANT_REJECTED", "Grant ancestry contains a cycle");
+    }
+    seen.add(current.grantId);
+    assertGrantCurrent(current, now, getOwn(state.revokedGrants, current.grantId));
+
+    if (current.parentGrantId) {
+      if (!current.reservationId) {
+        throw new AgentFabricError(
+          "AF_GRANT_REJECTED",
+          `Derived grant ${current.grantId} has no resource reservation`,
+        );
+      }
+      const reservation = getOwn(state.resourceReservations, current.reservationId);
+      if (!reservation || reservation.status === "released") {
+        throw new AgentFabricError(
+          "AF_GRANT_REJECTED",
+          `Derived grant ${current.grantId} has no current resource reservation`,
+        );
+      }
+    }
+
+    if (!current.parentGrantId) {
+      const authorization = getOwn(state.authorizations, current.rootAuthorizationId);
+      if (!authorization) {
+        throw new AgentFabricError(
+          "AF_GRANT_REJECTED",
+          `Root grant ${current.grantId} has no registered owner authorization`,
+        );
+      }
+      assertAuthorizationCurrent(
+        authorization,
+        now,
+        getOwn(state.revokedAuthorizations, authorization.authorizationId),
+      );
+      assertRootGrantAuthorized(authorization, current);
+      return;
+    }
+
+    const parent: ExecutionGrant | undefined = getOwn(state.grants, current.parentGrantId);
+    if (!parent) {
+      throw new AgentFabricError(
+        "AF_GRANT_REJECTED",
+        `Grant ${current.grantId} references missing parent ${current.parentGrantId}`,
+      );
+    }
+    assertGrantAttenuated(parent, current);
+    current = parent;
+  }
+}