forgeos 0.1.0-alpha.23 → 0.1.0-alpha.25

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.23 input=43fbd897d0f0a003e2f63e7048eb3281a5871034827653640e010161c0385d44 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
+// @forge-generated generator=0.1.0-alpha.25 input=f4bc0a51dfadbdbabe4e7083c29844716f74c2beebcb86ce30e7a70c4f9487b4 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+## 0.1.0-alpha.25
+
+### Patch Changes
+
+- Harden DeltaDB and Agent Memory under real `forge dev` concurrency.
+
+  - Stop long-running dev recorders from holding the DeltaDB writer lock between events.
+  - Retry short transient DeltaDB writer conflicts before reporting `FORGE_DELTA_BUSY`.
+  - Keep Codex hook queue checkpoints unchanged when Agent Memory ingest is blocked by a busy DeltaDB writer, then retry safely instead of losing queued events.
+  - Add watcher backoff metadata for lock recovery and document the safe queue/DeltaDB behavior.
+
+- Fix tenant-scope reporting in the generated agent contract and capability map.
+
+  - Match tenant-scoped tables by both authored/camelCase table names and generated SQL snake_case table names.
+  - Report camelCase liveQuery dependencies such as `onboardingTasks` as `tenant` scoped when `tenantScope.json` confirms `tenant_id`.
+  - Add regression coverage for the Team Onboarding style liveQuery/capability-map path.
+
+## 0.1.0-alpha.24
+
+### Patch Changes
+
+- Consolidate the public alpha adoption surface and agent-contract positioning.
+
+  - Add an explicit MIT `LICENSE`, package license metadata, and a private GitHub Security Advisory disclosure path.
+  - Add stable-alpha, AI-coding, agent demo, Convex, and agent-eval documentation pages, plus a runner-agnostic eval task scaffold.
+  - Fix `forge new --json` so scaffold automation receives structured JSON instead of human next-step text.
+  - Add the first `forge add convex` app-contract recipe with runtime placement guardrails, optional Convex environment names, generated docs, and a mock testkit.
+  - Expand field-report expectations and package/release tests for license, security disclosure, docs, create-app help, Convex recipes, and JSON scaffold output.
+
 ## 0.1.0-alpha.23
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeOS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # ForgeOS
 
-Agent-native application framework and compiler for building Forge apps without a mandatory dashboard. ForgeOS turns application source into deterministic runtime contracts, generated clients, safety checks, and machine-readable context that humans and AI coding agents can use safely.
+The contract layer for agentic software development. ForgeOS turns application source into deterministic runtime contracts, generated clients, safety checks, and machine-readable context that humans and AI coding agents can use safely.
 
 **Status:** private/public alpha MVP, implemented through H49. ForgeOS already includes the compiler, local runtime, frontend SDK, production auth, RLS compiler, liveQuery, self-host artifacts, generated agent contract, guided dev loop, repair/review/test tooling, AST-aware codemods, package intelligence, native AI tools/agents, DeltaDB work memory, external agent memory ingestion, brownfield import analysis, npm alpha publishing, and Read the Docs public docs. Public release hardening is still focused on deeper semantic codemods, broader field reports, and more production mileage.
 
@@ -8,7 +8,7 @@ Public docs live at [forgeos.readthedocs.io](https://forgeos.readthedocs.io/). T
 
 Start with [Why ForgeOS](https://forgeos.readthedocs.io/en/latest/why-forgeos/) to understand the agent-native design.
 
-For the short version, read [The Five-Minute ForgeOS Model](https://forgeos.readthedocs.io/en/latest/five-minute-model/) and [Alpha Golden Path](https://forgeos.readthedocs.io/en/latest/golden-path/). The important distinction is that external coding agents are the primary ForgeOS workflow; integrated AI SDK features are available for apps that need in-product AI, but they are not the main development loop.
+For the short version, read [The Five-Minute ForgeOS Model](https://forgeos.readthedocs.io/en/latest/five-minute-model/), [Alpha Golden Path](https://forgeos.readthedocs.io/en/latest/golden-path/), and [Stable Alpha Surface](https://forgeos.readthedocs.io/en/latest/stable-alpha/). The important distinction is that external coding agents are the primary ForgeOS workflow; integrated AI SDK features are available for apps that need in-product AI, but they are not the main development loop.
 
 ## Agent-First Quickstart
 

package/docs/changelog.md

@@ -6,6 +6,35 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.25
+
+- Hardened DeltaDB and Agent Memory for concurrent `forge dev` usage:
+  dev recorders now release the writer lock between events, Agent Memory ingest
+  retries short transient writer conflicts, and queued Codex hook events keep
+  their checkpoint unchanged when DeltaDB is temporarily busy.
+- Fixed tenant-scope reporting in the generated agent contract and capability
+  map for camelCase authored tables such as `onboardingTasks`, so liveQuery
+  dependencies now report `tenant` scope when `tenantScope.json` confirms the
+  table is tenant-scoped.
+- Added regression tests and docs for the DeltaDB lock recovery path and the
+  Team Onboarding style capability-map tenant-scope path.
+
+## 0.1.0-alpha.24
+
+- Consolidated the public alpha adoption surface: MIT license, package license
+  metadata, private GitHub Security Advisory disclosure, stable-alpha status
+  matrix, AI-coding loop, three short agent demos, and repeatable agent eval
+  task specs.
+- `forge new --json` now returns structured JSON for scaffold automation
+  instead of human next-step text.
+- Added the initial `forge add convex` app-contract recipe with runtime
+  placement guardrails, optional Convex environment names, generated docs, and
+  a mock testkit. The deeper Convex schema/API importer is documented as
+  planned rather than implied.
+- Expanded field-report expectations and release/doc tests for license,
+  security disclosure, create-app help, Convex recipes, and public docs
+  navigation.
+
 ## 0.1.0-alpha.23
 
 - Tightened the post-alpha.22 release surface and package evidence:

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.25",
   "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
   "type": "module",
+  "license": "MIT",
   "files": [
     "adapters/",
     "bin/",
@@ -18,6 +19,7 @@
     "src/forge/_generated/releaseManifest.ts",
     "templates/",
     "README.md",
+    "LICENSE",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "AGENTS.md",

package/src/forge/_generated/releaseManifest.json

@@ -1 +1 @@
-{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.23","releaseId":"forgeos@0.1.0-alpha.23+unknown","schemaVersion":"0.1.0"}
+{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.25","releaseId":"forgeos@0.1.0-alpha.25+unknown","schemaVersion":"0.1.0"}

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.23 input=43fbd897d0f0a003e2f63e7048eb3281a5871034827653640e010161c0385d44 content=8b537f90580f28c1630850bc7b7199e17d0bc62d05e9565fdf84da4bdbf9f6dc
+// @forge-generated generator=0.1.0-alpha.25 input=f4bc0a51dfadbdbabe4e7083c29844716f74c2beebcb86ce30e7a70c4f9487b4 content=a7c5e9f36b973e9b5a51716753739f57a63fa77c68b0fad18f059b5407aa58fe
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.23",
-  "releaseId": "forgeos@0.1.0-alpha.23+unknown",
+  "packageVersion": "0.1.0-alpha.25",
+  "releaseId": "forgeos@0.1.0-alpha.25+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/agent-memory/bridge.ts

@@ -113,10 +113,16 @@ async function openMemoryStore(
   workspaceRoot: string,
   access: "read" | "write" = "write",
 ): Promise<DeltaStore | AgentMemoryUnavailableResult> {
-  try {
-    return await DeltaStore.open(workspaceRoot, { access });
-  } catch (error) {
-    return memoryUnavailable(error, workspaceRoot);
+  const retryDelays = access === "write" ? [25, 75, 150] : [];
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await DeltaStore.open(workspaceRoot, { access });
+    } catch (error) {
+      if (!(error instanceof DeltaStoreBusyError) || attempt >= retryDelays.length) {
+        return memoryUnavailable(error, workspaceRoot);
+      }
+      await sleep(retryDelays[attempt] ?? 0);
+    }
   }
 }
 
@@ -131,6 +137,10 @@ function isExternalPgliteRead(result: AgentMemoryUnavailableResult): boolean {
   );
 }
 
+function isDeltaBusyIngestResult(result: AgentIngestResult): boolean {
+  return result.ok === false && result.busy?.code === "FORGE_DELTA_BUSY";
+}
+
 function fallbackMemoryPath(workspaceRoot: string): string {
   return join(workspaceRoot, ".forge", "agent", "events.ndjson");
 }
@@ -413,23 +423,29 @@ async function ingestAgentMemoryQueueFile(options: AgentMemoryCommandOptions): P
     source,
     eventName: options.eventName,
   });
+  const errors = [
+    ...drained.errors,
+    ...(drained.busy ? ["DeltaDB is busy; queue checkpoint was not advanced"] : []),
+  ];
   return {
-    ok: drained.errors.length === 0,
+    ok: errors.length === 0,
     watch: false,
     source,
     file: options.file,
     eventsIngested: drained.eventsIngested,
-    errors: drained.errors,
+    errors,
     bytesRead: drained.bytesRead,
     pendingBytes: drained.pendingBytes,
     checkpointFile: drained.checkpointFile,
     compacted: drained.compacted,
     historyFile: drained.historyFile,
+    ...(drained.busy ? { busy: drained.busy, pendingDueToBusy: true } : {}),
     nextActions: [
+      ...(drained.busy ? ["forge delta status --json"] : []),
       `forge agent memory --entry ${source} --json`,
       `forge agent hooks status --target ${source} --json`,
     ],
-    exitCode: drained.errors.length === 0 ? 0 : 1,
+    exitCode: errors.length === 0 ? 0 : 1,
   };
 }
 
@@ -644,6 +660,7 @@ export async function drainAgentMemoryQueueFile(options: {
   checkpointFile: string;
   compacted: boolean;
   historyFile: string;
+  busy?: AgentMemoryUnavailableResult["busy"];
 }> {
   const historyFile = queueHistoryPath(options.watchFile);
   if (!existsSync(options.watchFile)) {
@@ -699,6 +716,17 @@ export async function drainAgentMemoryQueueFile(options: {
       eventsIngested += 1;
       consumedOffset = bytesRead + line.endOffset;
       writeQueueCheckpoint(options.watchFile, consumedOffset);
+    } else if (isDeltaBusyIngestResult(result)) {
+      return {
+        eventsIngested,
+        errors,
+        bytesRead,
+        pendingBytes,
+        checkpointFile: queueCheckpointPath(options.watchFile),
+        compacted: false,
+        historyFile,
+        busy: result.busy,
+      };
     } else {
       errors.push(result.error ?? "agent memory ingest failed");
       break;
@@ -886,7 +914,19 @@ async function watchAgentMemoryIngest(options: AgentMemoryCommandOptions): Promi
 
   let eventsIngested = 0;
   const errors: string[] = [];
+  let busyRetries = 0;
+  let lastBusy: AgentMemoryUnavailableResult["busy"] | undefined;
   let pendingIngest = Promise.resolve();
+  let retryTimer: ReturnType<typeof setTimeout> | undefined;
+  const scheduleBusyRetry = () => {
+    if (retryTimer) {
+      return;
+    }
+    retryTimer = setTimeout(() => {
+      retryTimer = undefined;
+      pendingIngest = pendingIngest.then(ingestNewContent, ingestNewContent);
+    }, 500);
+  };
   const ingestNewContent = async () => {
     const result = await drainAgentMemoryQueueFile({
       workspaceRoot: options.workspaceRoot,
@@ -895,6 +935,13 @@ async function watchAgentMemoryIngest(options: AgentMemoryCommandOptions): Promi
       eventName: options.eventName,
     });
     eventsIngested += result.eventsIngested;
+    if (result.busy) {
+      busyRetries += 1;
+      lastBusy = result.busy;
+      scheduleBusyRetry();
+      return;
+    }
+    lastBusy = undefined;
     errors.push(...result.errors);
   };
 
@@ -904,6 +951,10 @@ async function watchAgentMemoryIngest(options: AgentMemoryCommandOptions): Promi
       pendingIngest = pendingIngest.then(ingestNewContent, ingestNewContent);
     });
     const shutdown = () => {
+      if (retryTimer) {
+        clearTimeout(retryTimer);
+        retryTimer = undefined;
+      }
       watcher.close();
       void pendingIngest.finally(() => {
         resolve({
@@ -913,7 +964,9 @@ async function watchAgentMemoryIngest(options: AgentMemoryCommandOptions): Promi
           file,
           eventsIngested,
           errors,
+          ...(lastBusy ? { busy: lastBusy, pendingDueToBusy: true, busyRetries } : {}),
           nextActions: [
+            ...(lastBusy ? ["forge delta status --json"] : []),
             `forge agent memory --entry ${source} --json`,
             `forge agent hooks status --target ${source} --json`,
           ],
@@ -971,6 +1024,10 @@ function installAgentMemory(options: AgentMemoryCommandOptions): AgentInstallRes
   return cursorInstallResult(filesWritten, planned);
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 export function formatAgentMemoryJson(result: AgentMemoryCommandResult): string {
   return `${JSON.stringify(result, null, 2)}\n`;
 }

package/src/forge/agent-memory/types.ts

@@ -155,6 +155,7 @@ export interface AgentIngestResult {
     path: string;
     reason: "pglite-active";
   };
+  busy?: AgentMemoryUnavailableResult["busy"];
   exitCode: 0 | 1;
   error?: string;
   diagnostics?: Diagnostic[];
@@ -174,6 +175,9 @@ export interface AgentIngestWatchResult {
   checkpointFile?: string;
   compacted?: boolean;
   historyFile?: string;
+  busy?: AgentMemoryUnavailableResult["busy"];
+  pendingDueToBusy?: boolean;
+  busyRetries?: number;
   nextActions: string[];
   exitCode: 0 | 1;
 }

package/src/forge/cli/commands.ts

@@ -168,7 +168,7 @@ import {
   runSecretsCommand,
 } from "./secrets.ts";
 import { formatAiHuman, formatAiJson, runAiCommand } from "./ai.ts";
-import { formatNewHuman, runNewCommand } from "./new.ts";
+import { formatNewHuman, formatNewJson, runNewCommand } from "./new.ts";
 import { formatBuildHuman, runBuildCommand } from "./build.ts";
 import { runServeCommand } from "./serve.ts";
 import { runWorkerCommand } from "./worker.ts";
@@ -1559,7 +1559,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
         localForge: command.localForge,
         workspaceRoot: command.workspaceRoot,
       });
-      process.stdout.write(formatNewHuman(result));
+      process.stdout.write(command.json ? formatNewJson(result) : formatNewHuman(result));
       return result.exitCode;
     }
     case "build": {

package/src/forge/cli/new.ts

@@ -535,3 +535,11 @@ export function formatNewHuman(result: NewCommandResult): string {
     "",
   ].join("\n");
 }
+
+export function formatNewJson(result: NewCommandResult): string {
+  return `${JSON.stringify({
+    schemaVersion: "0.1.0",
+    ok: result.exitCode === 0,
+    ...result,
+  }, null, 2)}\n`;
+}

package/src/forge/cli/parse.ts

@@ -63,6 +63,7 @@ export type ForgeCommand =
       git: boolean;
       forgePackageSpec?: string;
       localForge: boolean;
+      json: boolean;
       workspaceRoot: string;
     }
   | { kind: "build"; json: boolean; workspaceRoot: string }
@@ -860,6 +861,7 @@ export function parseCli(argv: string[]): ParsedCli {
           git: !parseFlag(argv, "--no-git"),
           forgePackageSpec,
           localForge,
+          json: parseFlag(argv, "--json"),
           workspaceRoot,
         },
         workspaceRoot,

package/src/forge/compiler/agent-contract/build.ts

@@ -7,6 +7,7 @@ import { detectSecrets } from "../classifier/secrets.ts";
 import { GENERATOR_VERSION } from "../emitter/constants.ts";
 import { stripDeterministicHeader } from "../primitives/header.ts";
 import { canonicalJson, normalizeNewlines, serializeCanonical } from "../primitives/serialize.ts";
+import { toSnakeCase } from "../data-graph/sql/naming.ts";
 import { resolveByPackageName } from "../recipes/registry.ts";
 import {
   defaultRuntimeCompatibility,
@@ -288,6 +289,35 @@ function runtimeRules(): AgentRuntimeRule[] {
   ];
 }
 
+type TenantTableInfo = {
+  tenantIdColumn: string;
+  tenantField: string;
+};
+
+function buildTenantTableLookup(tenantScope: TenantScope, dataGraph: DataGraph): Map<string, TenantTableInfo> {
+  const lookup = new Map<string, TenantTableInfo>();
+  for (const scoped of tenantScope.tables) {
+    const table = dataGraph.tables.find((candidate) =>
+      candidate.name === scoped.table ||
+      candidate.exportName === scoped.exportName ||
+      toSnakeCase(candidate.name) === scoped.table ||
+      toSnakeCase(candidate.exportName) === scoped.table
+    );
+    const tenantField = table?.fields.find((field) => toSnakeCase(field.name) === scoped.tenantIdColumn)?.name ??
+      scoped.tenantIdColumn;
+    const info = { tenantIdColumn: scoped.tenantIdColumn, tenantField };
+    for (const key of uniqueSorted([
+      scoped.table,
+      scoped.exportName,
+      table?.name,
+      table?.exportName,
+    ].filter((key): key is string => typeof key === "string" && key.length > 0))) {
+      lookup.set(key, info);
+    }
+  }
+  return lookup;
+}
+
 function agentProtocols(workspaceRoot: string): AgentProtocolInfo[] {
   return [
     {
@@ -1037,9 +1067,7 @@ export function buildAgentContractArtifacts(
   input: AgentContractInput,
 ): AgentContractArtifacts {
   const project = readPackageInfo(input.workspaceRoot);
-  const tenantTables = new Map(
-    input.tenantScope.tables.map((table) => [table.table, table.tenantIdColumn]),
-  );
+  const tenantTables = buildTenantTableLookup(input.tenantScope, input.dataGraph);
   const commandAuth = new Map(
     input.policyRegistry.commandAuth.map((binding) => [binding.commandName, binding.auth]),
   );
@@ -1183,13 +1211,16 @@ export function buildAgentContractArtifacts(
       }),
     ),
     data: {
-      tables: sorted(input.dataGraph.tables, (table) => table.name).map((table) => ({
-        name: table.name,
-        file: table.file,
-        tenantScoped: tenantTables.has(table.name),
-        ...(tenantTables.has(table.name) ? { tenantField: tenantTables.get(table.name) } : {}),
-        fields: uniqueSorted(table.fields.map((field) => field.name)),
-      })),
+      tables: sorted(input.dataGraph.tables, (table) => table.name).map((table) => {
+        const tenantInfo = tenantTables.get(table.name);
+        return {
+          name: table.name,
+          file: table.file,
+          tenantScoped: Boolean(tenantInfo),
+          ...(tenantInfo ? { tenantField: tenantInfo.tenantField } : {}),
+          fields: uniqueSorted(table.fields.map((field) => field.name)),
+        };
+      }),
     },
     policies: sorted(input.policyRegistry.policies, (policy) => policy.name).map((policy) => ({
       name: policy.name,

package/src/forge/compiler/integration/add.ts

@@ -549,7 +549,7 @@ export async function forgeAdd(
     const error = createDiagnostic({
       severity: "error",
       code: "FORGE_UNKNOWN_ALIAS",
-      message: `unknown integration alias '${alias}'; supported: stripe, posthog, sentry, zod, ai. For npm packages, use 'forge add package ${alias}' or 'forge add ${alias}'.`,
+      message: `unknown integration alias '${alias}'; supported: stripe, posthog, sentry, zod, convex, ai. For npm packages, use 'forge add package ${alias}' or 'forge add ${alias}'.`,
       suggestedCommands: [`forge add package ${alias} --dry-run --json`, "forge add --help"],
     });
     return finalizeAddResult({

package/src/forge/compiler/integration/templates/convex.ts

@@ -0,0 +1,70 @@
+import type { IntegrationTemplateInput } from "./types.ts";
+
+export function renderConvexTestkit(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated mock testkit for Convex app-contract evaluation. */",
+    "export interface ConvexFunctionRef {",
+    "  readonly kind: \"query\" | \"mutation\" | \"action\";",
+    "  readonly path: string;",
+    "}",
+    "",
+    "export function createConvexMock(functions: ConvexFunctionRef[] = []) {",
+    "  const calls: Array<{ path: string; args: unknown }> = [];",
+    "  return {",
+    "    functions,",
+    "    calls,",
+    "    call(path: string, args: unknown = {}) {",
+    "      calls.push({ path, args });",
+    "      return { ok: true, path, args } as const;",
+    "    },",
+    "  } as const;",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderConvexDoc(input: IntegrationTemplateInput): string {
+  return [
+    "# Convex integration",
+    "",
+    "Generated by Forge (recipe v1).",
+    "",
+    "Convex is treated as an agent-friendly backend package. ForgeOS treats it as an app-contract integration surface: package placement, frontend/backend usage, generated docs, and future function-map import.",
+    "",
+    "## Runtime placement",
+    "",
+    "- Use Convex client hooks and generated Convex APIs in frontend/client code.",
+    "- Use Convex server/admin clients only from server, action, workflow, or endpoint contexts.",
+    "- Do not import Convex runtime clients from Forge commands, queries, or liveQueries.",
+    "- Type-only imports are acceptable when the TypeScript compiler erases them.",
+    "",
+    "## App-contract import targets",
+    "",
+    "Future Convex import support should inspect:",
+    "",
+    "- `convex/schema.ts` for table names and fields;",
+    "- `convex/_generated/api.d.ts` for query, mutation, and action references;",
+    "- frontend `useQuery`, `useMutation`, and `useAction` calls for route/component capability mapping;",
+    "- auth and deployment notes from Convex config files.",
+    "",
+    "## Commands",
+    "",
+    "```bash",
+    "forge add convex",
+    "forge deps inspect convex --json",
+    "forge inspect runtime-matrix --json",
+    "forge check --json",
+    "```",
+    "",
+    "## Generated evidence",
+    "",
+    `Compatible contexts: ${input.compatible.join(", ")}`,
+    "",
+    `Incompatible contexts: ${input.incompatible.join(", ")}`,
+    "",
+    "Optional environment names:",
+    "",
+    ...input.secrets.map((secret) => `- ${secret.envVar}`),
+    "",
+  ].join("\n");
+}

package/src/forge/compiler/integration/templates/render.ts

@@ -1,5 +1,6 @@
 import type { IntegrationTemplateInput } from "./types.ts";
 import * as ai from "./ai.ts";
+import * as convex from "./convex.ts";
 import * as posthog from "./posthog.ts";
 import * as sentry from "./sentry.ts";
 import * as stripe from "./stripe.ts";
@@ -52,6 +53,7 @@ const TESTKIT_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
   stripe: { "stripe.mock.ts": stripe.renderStripeTestkit },
   posthog: { "posthog.mock.ts": posthog.renderPosthogTestkit },
   sentry: { "sentry.mock.ts": sentry.renderSentryTestkit },
+  convex: { "convex.mock.ts": convex.renderConvexTestkit },
   ai: { "ai.mock.ts": ai.renderAiTestkitLegacy },
 };
 
@@ -60,6 +62,7 @@ const DOC_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
   stripe: { "stripe.md": stripe.renderStripeDoc },
   posthog: { "posthog.md": posthog.renderPosthogDoc },
   sentry: { "sentry.md": sentry.renderSentryDoc },
+  convex: { "convex.md": convex.renderConvexDoc },
   ai: { "ai.md": ai.renderAiDoc },
 };
 

package/src/forge/compiler/recipes/definitions.ts

@@ -190,6 +190,30 @@ export const ZOD_RECIPE: IntegrationRecipe = {
   docs: ["zod.md"],
 };
 
+export const CONVEX_RECIPE: IntegrationRecipe = {
+  alias: "convex",
+  packages: [{ packageName: "convex" }],
+  supportedVersionRange: ">=1.0.0",
+  recipeVersion: "1.0.0",
+  contexts: {
+    allowed: ["client", "server", "action", "workflow", "endpoint", "test", "build"],
+    denied: ["shared", "query", "liveQuery", "command", "edge"],
+  },
+  capabilities: networkCapability(
+    ["*.convex.cloud", "*.convex.site"],
+    ["recipe:convex", "Convex client/server package connects to Convex deployments"],
+  ),
+  secrets: [
+    secret("NEXT_PUBLIC_CONVEX_URL", false),
+    secret("CONVEX_URL", false),
+    secret("CONVEX_DEPLOYMENT", false),
+    secret("CONVEX_DEPLOY_KEY", false),
+  ],
+  adapters: [],
+  testkits: ["convex.mock.ts"],
+  docs: ["convex.md"],
+};
+
 export const FORGE_RECIPE: IntegrationRecipe = {
   alias: "forge",
   packages: [{ packageName: "forge" }],
@@ -283,6 +307,7 @@ export const REFERENCE_ALIASES = [
   "posthog",
   "sentry",
   "zod",
+  "convex",
   "ai",
 ] as const;
 

package/src/forge/compiler/recipes/index.ts

@@ -15,6 +15,7 @@ export {
   POSTHOG_RECIPE,
   SENTRY_RECIPE,
   ZOD_RECIPE,
+  CONVEX_RECIPE,
   AI_RECIPE,
   AI_PROVIDER_RECIPES,
 } from "./definitions.ts";

package/src/forge/compiler/recipes/registry.ts

@@ -3,6 +3,7 @@ import type { PackageRecipe } from "../types/integration.ts";
 import {
   AI_PROVIDER_RECIPES,
   AI_RECIPE,
+  CONVEX_RECIPE,
   FORGE_RECIPE,
   POSTHOG_RECIPE,
   REFERENCE_ALIASES,
@@ -23,6 +24,7 @@ const REFERENCE_RECIPES: Record<string, IntegrationRecipe> = {
   posthog: POSTHOG_RECIPE,
   sentry: SENTRY_RECIPE,
   zod: ZOD_RECIPE,
+  convex: CONVEX_RECIPE,
   forge: FORGE_RECIPE,
   ai: AI_RECIPE,
 };
@@ -32,6 +34,7 @@ const ALL_RECIPES: IntegrationRecipe[] = [
   POSTHOG_RECIPE,
   SENTRY_RECIPE,
   ZOD_RECIPE,
+  CONVEX_RECIPE,
   FORGE_RECIPE,
   AI_RECIPE,
   ...AI_PROVIDER_RECIPES,

package/src/forge/delta/recorder.ts

@@ -4,7 +4,7 @@ import type { ForgeCommand } from "../cli/parse.ts";
 import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
 import { normalizePath } from "../compiler/primitives/paths.ts";
 import { hashUtf8Bytes } from "../compiler/primitives/hash.ts";
-import { DeltaStore, type DeltaRuntimeCallInput } from "./store.ts";
+import { DeltaStore, DeltaStoreBusyError, type DeltaRuntimeCallInput } from "./store.ts";
 import { classifyArtifactKind } from "./classifier.ts";
 import { readDeltaGitSnapshot } from "./git-observer.ts";
 
@@ -28,70 +28,129 @@ export async function createAmbientDeltaRecorder(
   if (isDeltaDisabled()) {
     return noopRecorder;
   }
-  try {
-    const store = await DeltaStore.open(workspaceRoot);
-    const actorId = await store.ensureActor("forge", "forge-cli", { pid: process.pid });
-    const sessionId = await store.createSession({
+  let actorId: string | undefined;
+  let sessionId: string | undefined;
+  let accepting = true;
+  let closed = false;
+  let queue = Promise.resolve();
+
+  const withStore = async (fn: (store: DeltaStore) => Promise<void>): Promise<void> => {
+    const store = await openDeltaStoreWithRetry(workspaceRoot);
+    try {
+      await fn(store);
+    } finally {
+      await store.close();
+    }
+  };
+
+  const enqueue = (fn: (store: DeltaStore) => Promise<void>): Promise<void> => {
+    queue = queue.then(() => safeDelta(() => withStore(fn)));
+    return queue;
+  };
+
+  const ensureSession = async (store: DeltaStore): Promise<{ actorId: string; sessionId: string } | null> => {
+    if (actorId && sessionId) {
+      return { actorId, sessionId };
+    }
+    actorId = await store.ensureActor("forge", "forge-cli", { pid: process.pid });
+    sessionId = await store.createSession({
       source,
       summary,
       metadata: { actorId },
       git: readDeltaGitSnapshot(workspaceRoot),
     });
-    return {
-      sessionId,
-      async recordRuntimeCall(input) {
-        await safeDelta(async () => {
-          const failedCode = input.diagnosticCode ?? diagnosticCode(input.diagnostics);
-          await store.appendOperation({
-            sessionId,
-            actorId,
-            kind: input.result === "denied"
-              ? "runtime.entry.denied"
-              : input.result === "failed"
-                ? "runtime.entry.failed"
-                : "runtime.entry.executed",
-            summary: `${input.entryName} ${input.result ?? "executed"}`,
-            data: {
-              entryName: input.entryName,
-              entryKind: input.entryKind,
-              result: input.result,
-              traceId: input.traceId,
-              diagnosticCode: failedCode,
-            },
-            runtimeCall: { ...input, diagnosticCode: failedCode },
-          });
-        });
-      },
-      async recordAgentTool(input) {
-        await safeDelta(async () => {
-          await store.appendOperation({
-            sessionId,
-            actorId,
-            kind: "agent.tool.called",
-            summary: `${input.toolName} ${input.status}`,
-            data: {
-              toolName: input.toolName,
-              risk: input.risk,
-              status: input.status,
-              traceId: input.traceId,
-              durationMs: input.durationMs,
-            },
-          });
+    return { actorId, sessionId };
+  };
+
+  await enqueue(async (store) => {
+    await ensureSession(store);
+  });
+
+  return {
+    get sessionId() {
+      return sessionId;
+    },
+    async recordRuntimeCall(input) {
+      if (!accepting) {
+        return;
+      }
+      await enqueue(async (store) => {
+        const session = await ensureSession(store);
+        if (!session) {
+          return;
+        }
+        const failedCode = input.diagnosticCode ?? diagnosticCode(input.diagnostics);
+        await store.appendOperation({
+          sessionId: session.sessionId,
+          actorId: session.actorId,
+          kind: input.result === "denied"
+            ? "runtime.entry.denied"
+            : input.result === "failed"
+              ? "runtime.entry.failed"
+              : "runtime.entry.executed",
+          summary: `${input.entryName} ${input.result ?? "executed"}`,
+          data: {
+            entryName: input.entryName,
+            entryKind: input.entryKind,
+            result: input.result,
+            traceId: input.traceId,
+            diagnosticCode: failedCode,
+          },
+          runtimeCall: { ...input, diagnosticCode: failedCode },
         });
-      },
-      async recordFileChanged(path, changeType = "modified") {
-        await safeDelta(() => store.recordFilePath(sessionId, path, changeType));
-      },
-      async close(closeSummary) {
-        await safeDelta(async () => {
-          await store.endSession(sessionId, closeSummary);
-          await store.close();
+      });
+    },
+    async recordAgentTool(input) {
+      if (!accepting) {
+        return;
+      }
+      await enqueue(async (store) => {
+        const session = await ensureSession(store);
+        if (!session) {
+          return;
+        }
+        await store.appendOperation({
+          sessionId: session.sessionId,
+          actorId: session.actorId,
+          kind: "agent.tool.called",
+          summary: `${input.toolName} ${input.status}`,
+          data: {
+            toolName: input.toolName,
+            risk: input.risk,
+            status: input.status,
+            traceId: input.traceId,
+            durationMs: input.durationMs,
+          },
         });
-      },
-    };
-  } catch {
-    return noopRecorder;
-  }
+      });
+    },
+    async recordFileChanged(path, changeType = "modified") {
+      if (!accepting) {
+        return;
+      }
+      await enqueue(async (store) => {
+        const session = await ensureSession(store);
+        if (!session) {
+          return;
+        }
+        await store.recordFilePath(session.sessionId, path, changeType);
+      });
+    },
+    async close(closeSummary) {
+      if (closed) {
+        await queue;
+        return;
+      }
+      accepting = false;
+      closed = true;
+      await enqueue(async (store) => {
+        if (!sessionId) {
+          return;
+        }
+        await store.endSession(sessionId, closeSummary);
+      });
+    },
+  };
 }
 
 export async function recordParsedCliCommand(input: {
@@ -343,6 +402,25 @@ const noopRecorder: AmbientDeltaRecorder = {
   async close() {},
 };
 
+const DELTA_STORE_RETRY_DELAYS_MS = [25, 75, 150];
+
+async function openDeltaStoreWithRetry(workspaceRoot: string): Promise<DeltaStore> {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await DeltaStore.open(workspaceRoot);
+    } catch (error) {
+      if (!(error instanceof DeltaStoreBusyError) || attempt >= DELTA_STORE_RETRY_DELAYS_MS.length) {
+        throw error;
+      }
+      await sleep(DELTA_STORE_RETRY_DELAYS_MS[attempt] ?? 0);
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 async function safeDelta(fn: () => Promise<void>): Promise<void> {
   try {
     await fn();

package/src/forge/version.ts

@@ -1,3 +1,3 @@
-export const FORGEOS_VERSION = "0.1.0-alpha.23";
+export const FORGEOS_VERSION = "0.1.0-alpha.25";
 export const GENERATOR_VERSION = FORGEOS_VERSION;
 export const CLI_VERSION = FORGEOS_VERSION;