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

package/src/forge/agent-fabric/repository-context.ts

@@ -0,0 +1,83 @@
+import { readRepositoryManifest } from "../repository-manifest/index.ts";
+import { analyzeRepository } from "../repository-analysis/analyze.ts";
+import { repositoryContext } from "../repository-analysis/context.ts";
+import { readRepositorySnapshot } from "../repository-analysis/context.ts";
+import { existsSync } from "node:fs";
+import { readRuntimeObservation, runtimeSourceDigest, selectRuntimeObservation } from "../repository-analysis/runtime-observation.ts";
+import { join } from "node:path";
+import { selectRepositoryContext } from "../repository-analysis/retrieval.ts";
+import { selectRepositoryChecks } from "../repository-analysis/check-selection.ts";
+import { repositoryQualitySummary, type RepositoryQualitySummary } from "../repository-analysis/quality.ts";
+
+export interface FabricRepositoryContextMetadata {
+  provider: "repository";
+  phase: "prepared-input";
+  status: "ready" | "unavailable";
+  sourceRoot: string;
+  cloneRoot: string;
+  snapshotId?: string;
+  diagnostics: string[];
+  quality?: RepositoryQualitySummary;
+  runtime?: { reportId: string; environmentId: string; phase: "source-observed-matching-input" };
+}
+
+/** Optional static maps, taken from the clone after upstream composition and preparation.
+ * Nothing is written: an analysis cache in the clone would violate artifact write scope.
+ * Suggested checks are never executed here and maps never relax publication obligations.
+ */
+export async function prepareFabricRepositoryContext(sourceRoot: string, cloneRoot: string, query: string, scope: string[] = []): Promise<{ metadata: FabricRepositoryContextMetadata; prompt: string } | undefined> {
+  let loaded: ReturnType<typeof readRepositoryManifest>;
+  try { loaded = readRepositoryManifest(cloneRoot); }
+  catch { loaded = { manifest: null, diagnostics: ["Repository manifest cannot be read safely"] }; }
+  const { manifest, diagnostics } = loaded;
+  if (!manifest && !diagnostics.length) return undefined;
+  // JSON parser diagnostics can echo source values. Public worker metadata needs only
+  // an actionable status; detailed manifest validation is a separate user operation.
+  const metadata: FabricRepositoryContextMetadata = { provider: "repository", phase: "prepared-input", status: "unavailable", sourceRoot, cloneRoot, diagnostics: diagnostics.length ? ["Repository manifest missing, invalid or unsafe"] : [] };
+  if (!manifest) return { metadata, prompt: "Repository maps unavailable: invalid manifest. Inspect the code directly; no analysis result is claimed." };
+  try {
+    const snapshot = await analyzeRepository(cloneRoot, manifest, { write: false, factsCacheRoot: join(sourceRoot, ".forge", "repository") });
+    // Executor prompts are natural-language instructions, not CAIR query programs.
+    const context = await repositoryContext(cloneRoot, snapshot, `locate ${query.slice(0, 1000)}`, { snapshotId: snapshot.snapshotId, maxChars: 12000, limit: 20, includeSource: false });
+    metadata.snapshotId = snapshot.snapshotId;
+    metadata.diagnostics = context.diagnostics.slice(0, 20).map(item => item.slice(0, 512));
+    if (!context.ok) return { metadata, prompt: "Repository maps unavailable or stale. Inspect current clone files directly; do not reuse source-checkout analysis." };
+    metadata.quality = repositoryQualitySummary(snapshot);
+    const selection = selectRepositoryContext(snapshot, query, { writeScope: scope, maxChars: 10000, maxNodes: 30, maxEdges: 30 });
+    const checks = selectRepositoryChecks(snapshot, { scope, nodeIds: selection.nodes.map(node => node.id) }).checks.slice(0, 10);
+    // An observation is supplementary evidence about the source input, never an
+    // assertion that the SDK worker ran the application. Upstream composition or
+    // another manifest/scenario must invalidate reuse even when task files match.
+    let runtime: unknown;
+    if (existsSync(join(sourceRoot, ".forge/repository/runtime-observation.json"))) {
+      try {
+        const sourceSnapshot = readRepositorySnapshot(sourceRoot);
+        if (sourceSnapshot) {
+          const report = readRuntimeObservation(sourceRoot, sourceSnapshot);
+          if (report.binding.manifestHash === snapshot.manifestHash && report.binding.scenarioHash === snapshot.scenarioHash
+            && runtimeSourceDigest(cloneRoot, manifest) === report.binding.inputDigest) {
+            runtime = selectRuntimeObservation(report, { query, scope: [...new Set(selection.nodes.map(node => node.component))], maxChars: 4000 });
+            metadata.runtime = { reportId: report.reportId, environmentId: report.environmentId, phase: "source-observed-matching-input" };
+          }
+        }
+      } catch { /* Missing/stale observations cannot downgrade valid static maps. */ }
+    }
+    const packet = { ...selection, cloneRoot, quality: metadata.quality, coverage: { found: snapshot.coverage.found, analyzed: snapshot.coverage.analyzed,
+      unsupported: snapshot.coverage.unsupported, errors: snapshot.coverage.errors, limitations: snapshot.coverage.limitations.slice(0, 10) },
+      suggestedCheckIds: checks.map(check => ({ id: check.id, component: check.component })), suggestedChecks: checks, runtime };
+    if (JSON.stringify(packet).length > 16000 && runtime) { delete packet.runtime; delete metadata.runtime; packet.truncated = true; }
+    while (JSON.stringify(packet).length > 16000 && packet.suggestedChecks.length) { packet.suggestedChecks.pop(); packet.suggestedCheckIds.pop(); packet.truncated = true; }
+    const serialized = JSON.stringify(packet);
+    const text = serialized.length <= 16000 ? serialized : JSON.stringify({ snapshotId: snapshot.snapshotId, cloneRoot, truncated: true, reason: "Context packet exceeded budget; inspect clone directly" });
+    metadata.status = "ready";
+    return { metadata, prompt: `Repository analysis of THIS prepared clone (static evidence, not executed coverage). Optional runtime evidence was observed in an independent source copy with matching input, not executed in this worker clone; it describes only its recorded scenario and time. Source project identity: ${sourceRoot}. Ready means input prepared, not semantic completeness. Snapshot handles apply only to this snapshot. Read-only neighbors never extend write scope. Suggested checks are informational; only authorized workflow executors run checks. Maps do not replace required review, verification or file scope.\n${text}` };
+  } catch {
+    // Analysis is an optional aid. Do not expose parser exceptions or claim a fallback
+    // graph from the source checkout; the existing worker and publication gates remain.
+    metadata.status = "unavailable";
+    delete metadata.quality;
+    delete metadata.runtime;
+    metadata.diagnostics = ["Repository analysis unavailable in this prepared clone"];
+    return { metadata, prompt: "Repository analysis failed in this clone. Inspect the current files directly; no map evidence is available." };
+  }
+}

package/src/forge/agent-fabric/resource-ledger.ts

@@ -0,0 +1,266 @@
+import { getOwn, setOwn } from "./dictionary.ts";
+import { stableStringify } from "./canonical.ts";
+import { AgentFabricError } from "./errors.ts";
+import type {
+  Identifier,
+  ResourceDefinition,
+  ResourceLedgerSnapshot,
+  ResourceReservation,
+  ResourceReservationRequest,
+} from "./types.ts";
+
+function assertAmount(amount: number, resource: string): void {
+  if (!Number.isFinite(amount) || amount <= 0) {
+    throw new AgentFabricError(
+      "AF_RESOURCE_EXHAUSTED",
+      `Resource amount for ${resource} must be finite and greater than zero`,
+      { amount, resource },
+    );
+  }
+}
+
+function bucket(
+  records: Record<Identifier, Record<string, number>>,
+  ownerId: Identifier,
+): Record<string, number> {
+  return getOwn(records, ownerId) ?? setOwn(records, ownerId, {});
+}
+
+function replaceRecord<T>(target: Record<string, T>, source: Readonly<Record<string, T>>): void {
+  for (const key of Object.keys(target)) delete target[key];
+  for (const [key, value] of Object.entries(source)) setOwn(target, key, structuredClone(value));
+}
+
+export class ResourceLedger {
+  private readonly definitions: Record<string, ResourceDefinition>;
+  private readonly reserved: Record<string, number> = {};
+  private readonly consumed: Record<string, number> = {};
+  private readonly ownerReserved: Record<Identifier, Record<string, number>> = {};
+  private readonly ownerConsumed: Record<Identifier, Record<string, number>> = {};
+  private readonly reservations: Record<Identifier, ResourceReservation> = {};
+
+  constructor(definitions: readonly ResourceDefinition[]) {
+    this.definitions = {};
+    for (const definition of definitions) {
+      if (getOwn(this.definitions, definition.resource)) {
+        throw new AgentFabricError(
+          "AF_DUPLICATE_ID",
+          `Duplicate resource definition: ${definition.resource}`,
+        );
+      }
+      if (!Number.isFinite(definition.limit) || definition.limit < 0) {
+        throw new AgentFabricError(
+          "AF_INVALID_STATE",
+          `Resource limit for ${definition.resource} must be finite and non-negative`,
+        );
+      }
+      setOwn(this.definitions, definition.resource, { ...definition });
+      setOwn(this.reserved, definition.resource, 0);
+      setOwn(this.consumed, definition.resource, 0);
+    }
+  }
+
+  static fromSnapshot(snapshot: ResourceLedgerSnapshot): ResourceLedger {
+    const ledger = new ResourceLedger(Object.values(snapshot.definitions));
+    const freshDefinitions = ledger.snapshot().definitions;
+    if (stableStringify(freshDefinitions) !== stableStringify(snapshot.definitions)) {
+      throw new AgentFabricError(
+        "AF_INVALID_STATE",
+        "ResourceLedger snapshot definitions are not canonical",
+      );
+    }
+    ledger.restore(snapshot);
+    return ledger;
+  }
+
+  transaction<T>(operation: () => T): T {
+    const before = this.snapshot();
+    try {
+      return operation();
+    } catch (error) {
+      this.restore(before);
+      throw error;
+    }
+  }
+
+  reserve(
+    reservationId: Identifier,
+    ownerId: Identifier,
+    requests: readonly ResourceReservationRequest[],
+    ownerCeilings?: Readonly<Record<string, number>>,
+  ): ResourceReservation {
+    const aggregated: Record<string, number> = {};
+    for (const request of requests) {
+      assertAmount(request.amount, request.resource);
+      if (!getOwn(this.definitions, request.resource)) {
+        throw new AgentFabricError(
+          "AF_NOT_FOUND",
+          `Unknown resource: ${request.resource}`,
+        );
+      }
+      setOwn(aggregated, request.resource, (getOwn(aggregated, request.resource) ?? 0) + request.amount);
+    }
+
+    const normalizedRequests = Object.entries(aggregated)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([resource, amount]) => ({ resource, amount }));
+
+    const existing = getOwn(this.reservations, reservationId);
+    if (existing) {
+      const requested = stableStringify({ ownerId, requests: normalizedRequests });
+      const recorded = stableStringify({ ownerId: existing.ownerId, requests: existing.requests });
+      if (requested !== recorded) {
+        throw new AgentFabricError(
+          "AF_CONFLICT",
+          `Reservation ${reservationId} was reused with a different request`,
+        );
+      }
+      return structuredClone(existing);
+    }
+
+    const ownerReserved = getOwn(this.ownerReserved, ownerId) ?? {};
+    const ownerConsumed = getOwn(this.ownerConsumed, ownerId) ?? {};
+    for (const [resource, amount] of Object.entries(aggregated)) {
+      const definition = getOwn(this.definitions, resource)!;
+      const reserved = getOwn(this.reserved, resource) ?? 0;
+      const consumed = getOwn(this.consumed, resource) ?? 0;
+      const projected = definition.semantics === "counter"
+        ? consumed + amount
+        : reserved + consumed + amount;
+      if (projected > definition.limit) {
+        throw new AgentFabricError(
+          "AF_RESOURCE_EXHAUSTED",
+          `Resource ${resource} would exceed its global limit`,
+          { amount, consumed, limit: definition.limit, reserved, resource },
+        );
+      }
+
+      if (ownerCeilings) {
+        const ceiling = getOwn(ownerCeilings, resource);
+        if (ceiling === undefined) {
+          throw new AgentFabricError(
+            "AF_RESOURCE_EXHAUSTED",
+            `Owner ${ownerId} has no ceiling for resource ${resource}`,
+            { ownerId, resource },
+          );
+        }
+        const ownerProjected = definition.semantics === "counter"
+          ? (getOwn(ownerConsumed, resource) ?? 0) + amount
+          : (getOwn(ownerReserved, resource) ?? 0) + (getOwn(ownerConsumed, resource) ?? 0) + amount;
+        if (ownerProjected > ceiling) {
+          throw new AgentFabricError(
+            "AF_RESOURCE_EXHAUSTED",
+            `Resource ${resource} would exceed the ceiling for ${ownerId}`,
+            { amount, ceiling, ownerId, projected: ownerProjected, resource },
+          );
+        }
+      }
+    }
+
+    // Publish owner buckets only after validation, including for callers that
+    // translate a reservation exception into a rejected AuthorityResolution.
+    getOwn(this.ownerReserved, ownerId) ?? setOwn(this.ownerReserved, ownerId, ownerReserved);
+    getOwn(this.ownerConsumed, ownerId) ?? setOwn(this.ownerConsumed, ownerId, ownerConsumed);
+    for (const request of normalizedRequests) {
+      const definition = getOwn(this.definitions, request.resource)!;
+      if (definition.semantics === "counter") {
+        setOwn(this.consumed, request.resource, (getOwn(this.consumed, request.resource) ?? 0) + request.amount);
+        setOwn(ownerConsumed, request.resource, (getOwn(ownerConsumed, request.resource) ?? 0) + request.amount);
+      } else {
+        setOwn(this.reserved, request.resource, (getOwn(this.reserved, request.resource) ?? 0) + request.amount);
+        setOwn(ownerReserved, request.resource, (getOwn(ownerReserved, request.resource) ?? 0) + request.amount);
+      }
+    }
+
+    const reservation: ResourceReservation = {
+      reservationId,
+      ownerId,
+      requests: normalizedRequests,
+      status: normalizedRequests.some(
+        (request) => getOwn(this.definitions, request.resource)?.semantics !== "counter",
+      ) ? "active" : "consumed",
+    };
+    setOwn(this.reservations, reservationId, structuredClone(reservation));
+    return structuredClone(reservation);
+  }
+
+  consume(reservationId: Identifier): ResourceReservation {
+    const reservation = this.requireReservation(reservationId);
+    if (reservation.status !== "active") return structuredClone(reservation);
+
+    const ownerReserved = bucket(this.ownerReserved, reservation.ownerId);
+    const ownerConsumed = bucket(this.ownerConsumed, reservation.ownerId);
+    for (const request of reservation.requests) {
+      const definition = getOwn(this.definitions, request.resource)!;
+      if (definition.semantics === "capacity") continue;
+      if (definition.semantics === "consumable") {
+        setOwn(this.reserved, request.resource, getOwn(this.reserved, request.resource)! - request.amount);
+        setOwn(this.consumed, request.resource, getOwn(this.consumed, request.resource)! + request.amount);
+        setOwn(ownerReserved, request.resource, (getOwn(ownerReserved, request.resource) ?? 0) - request.amount);
+        setOwn(ownerConsumed, request.resource, (getOwn(ownerConsumed, request.resource) ?? 0) + request.amount);
+      }
+    }
+
+    const next: ResourceReservation = { ...reservation, status: "consumed" };
+    setOwn(this.reservations, reservationId, structuredClone(next));
+    return structuredClone(next);
+  }
+
+  release(reservationId: Identifier): ResourceReservation {
+    const reservation = this.requireReservation(reservationId);
+    if (reservation.status === "released") return structuredClone(reservation);
+
+    const ownerReserved = bucket(this.ownerReserved, reservation.ownerId);
+    if (reservation.status === "active") {
+      for (const request of reservation.requests) {
+        const definition = getOwn(this.definitions, request.resource)!;
+        if (definition.semantics !== "counter") {
+          setOwn(this.reserved, request.resource, getOwn(this.reserved, request.resource)! - request.amount);
+          setOwn(ownerReserved, request.resource, (getOwn(ownerReserved, request.resource) ?? 0) - request.amount);
+        }
+      }
+    } else {
+      for (const request of reservation.requests) {
+        const definition = getOwn(this.definitions, request.resource)!;
+        if (definition.semantics === "capacity") {
+          setOwn(this.reserved, request.resource, getOwn(this.reserved, request.resource)! - request.amount);
+          setOwn(ownerReserved, request.resource, (getOwn(ownerReserved, request.resource) ?? 0) - request.amount);
+        }
+      }
+    }
+
+    const next: ResourceReservation = { ...reservation, status: "released" };
+    setOwn(this.reservations, reservationId, structuredClone(next));
+    return structuredClone(next);
+  }
+
+  snapshot(): ResourceLedgerSnapshot {
+    return {
+      definitions: structuredClone(this.definitions),
+      reserved: { ...this.reserved },
+      consumed: { ...this.consumed },
+      ownerReserved: structuredClone(this.ownerReserved),
+      ownerConsumed: structuredClone(this.ownerConsumed),
+      reservations: structuredClone(this.reservations),
+    };
+  }
+
+  private restore(snapshot: ResourceLedgerSnapshot): void {
+    replaceRecord(this.reserved, snapshot.reserved);
+    replaceRecord(this.consumed, snapshot.consumed);
+    replaceRecord(this.ownerReserved, snapshot.ownerReserved as Readonly<Record<string, Record<string, number>>>);
+    replaceRecord(this.ownerConsumed, snapshot.ownerConsumed as Readonly<Record<string, Record<string, number>>>);
+    replaceRecord(this.reservations, snapshot.reservations);
+  }
+
+  private requireReservation(reservationId: Identifier): ResourceReservation {
+    const reservation = getOwn(this.reservations, reservationId);
+    if (!reservation) {
+      throw new AgentFabricError(
+        "AF_NOT_FOUND",
+        `Unknown reservation: ${reservationId}`,
+      );
+    }
+    return reservation;
+  }
+}

package/src/forge/agent-fabric/serialized-local-adapter.ts

@@ -0,0 +1,60 @@
+import type { DbAdapter, DbQueryResult, DbTransaction } from "../runtime/db/adapter.ts";
+
+/** Keep all local inbox queries outside a control-journal transaction. */
+export function serializeLocalAdapter(adapter: DbAdapter): DbAdapter {
+  let tail: Promise<void> = Promise.resolve();
+  let poisoned = false;
+  const acquire = async (): Promise<() => void> => {
+    const predecessor = tail;
+    let release!: () => void;
+    tail = new Promise<void>((resolve) => { release = resolve; });
+    await predecessor;
+    return release;
+  };
+  const query = async (sql: string, params?: unknown[]): Promise<DbQueryResult> => {
+    const release = await acquire();
+    try {
+      if (poisoned) throw new Error("Local database transaction recovery failed");
+      return await adapter.query(sql, params);
+    } finally { release(); }
+  };
+  return {
+    kind: adapter.kind,
+    query,
+    async begin(): Promise<DbTransaction> {
+      const release = await acquire();
+      if (poisoned) { release(); throw new Error("Local database transaction recovery failed"); }
+      let transaction: DbTransaction;
+      try { transaction = await adapter.begin(); } catch (error) { release(); throw error; }
+      let finished = false;
+      const finish = async (kind: "commit" | "rollback"): Promise<void> => {
+        if (finished) throw new Error("Local database transaction is already closed");
+        try {
+          await transaction[kind]();
+        } catch (error) {
+          if (kind === "commit") {
+            try { await transaction.rollback(); } catch { poisoned = true; }
+          } else {
+            poisoned = true;
+          }
+          throw error;
+        } finally {
+          finished = true;
+          release();
+        }
+      };
+      return {
+        query: (sql, params) => {
+          if (finished) throw new Error("Local database transaction is already closed");
+          return transaction.query(sql, params);
+        },
+        commit: () => finish("commit"),
+        rollback: () => finish("rollback"),
+      };
+    },
+    async close(): Promise<void> {
+      const release = await acquire();
+      try { await adapter.close(); } finally { release(); }
+    },
+  };
+}