forgeos 0.1.0-alpha.2 → 0.1.0-alpha.20

package/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeSpringRuntime.java

@@ -0,0 +1,104 @@
+package dev.forgeos.adapter.spring;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import dev.forgeos.adapter.Forge;
+import dev.forgeos.adapter.ForgeContext;
+import dev.forgeos.adapter.ForgeHandler;
+import dev.forgeos.adapter.ForgeRegistry;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import org.springframework.aop.support.AopUtils;
+import org.springframework.context.ApplicationContext;
+import org.springframework.core.annotation.AnnotatedElementUtils;
+import org.springframework.util.ReflectionUtils;
+
+public final class ForgeSpringRuntime {
+  private ForgeSpringRuntime() {
+  }
+
+  public static ForgeRegistry buildRegistry(ApplicationContext context) {
+    String[] serviceBeanNames = context.getBeanNamesForAnnotation(ForgeExternalService.class);
+    if (serviceBeanNames.length == 0) {
+      throw new IllegalStateException("no @ForgeExternalService bean found");
+    }
+
+    Object serviceBean = context.getBean(serviceBeanNames[0]);
+    Class<?> serviceClass = AopUtils.getTargetClass(serviceBean);
+    ForgeExternalService service = AnnotatedElementUtils.findMergedAnnotation(
+        serviceClass,
+        ForgeExternalService.class
+    );
+    if (service == null) {
+      throw new IllegalStateException("selected bean is missing @ForgeExternalService");
+    }
+
+    ForgeRegistry registry = Forge.service(service.name(),
+        Forge.framework(service.framework()),
+        Forge.baseUrl(service.baseUrl()),
+        Forge.health(service.health())
+    );
+
+    ReflectionUtils.doWithMethods(serviceClass, method -> registerMethod(registry, serviceBean, method));
+    return registry;
+  }
+
+  private static void registerMethod(ForgeRegistry registry, Object bean, Method method) {
+    ForgeCommand command = AnnotatedElementUtils.findMergedAnnotation(method, ForgeCommand.class);
+    if (command != null) {
+      registry.command(command.name(), handlerFor(bean, method),
+          command.description().isBlank() ? entry -> { } : Forge.description(command.description()),
+          command.path().isBlank() ? entry -> { } : Forge.path(command.path()),
+          command.policy().isBlank() ? entry -> { } : Forge.policy(command.policy()),
+          Forge.tenantScoped(command.tenantScoped()),
+          Forge.transaction(command.transaction()),
+          Forge.risk(command.risk()),
+          Forge.needsApproval(command.needsApproval()),
+          Forge.effects(command.effects())
+      );
+    }
+
+    ForgeQuery query = AnnotatedElementUtils.findMergedAnnotation(method, ForgeQuery.class);
+    if (query != null) {
+      registry.query(query.name(), handlerFor(bean, method),
+          query.description().isBlank() ? entry -> { } : Forge.description(query.description()),
+          query.path().isBlank() ? entry -> { } : Forge.path(query.path()),
+          query.policy().isBlank() ? entry -> { } : Forge.policy(query.policy()),
+          Forge.tenantScoped(query.tenantScoped()),
+          Forge.readOnly()
+      );
+    }
+  }
+
+  private static ForgeHandler handlerFor(Object bean, Method method) {
+    ReflectionUtils.makeAccessible(method);
+    return (context, args) -> {
+      try {
+        return method.invoke(bean, argumentsFor(method, context, args));
+      } catch (InvocationTargetException error) {
+        Throwable target = error.getTargetException();
+        if (target instanceof Exception exception) {
+          throw exception;
+        }
+        throw new RuntimeException(target);
+      }
+    };
+  }
+
+  private static Object[] argumentsFor(Method method, ForgeContext context, JsonNode args) throws Exception {
+    Parameter[] parameters = method.getParameters();
+    Object[] values = new Object[parameters.length];
+    for (int index = 0; index < parameters.length; index += 1) {
+      Class<?> type = parameters[index].getType();
+      if (type.equals(ForgeContext.class)) {
+        values[index] = context;
+      } else {
+        JsonNode safeArgs = args == null || args.isNull()
+            ? dev.forgeos.adapter.Json.MAPPER.createObjectNode()
+            : args;
+        values[index] = dev.forgeos.adapter.Json.MAPPER.treeToValue(safeArgs, type);
+      }
+    }
+    return values;
+  }
+}

package/adapters/java-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -0,0 +1 @@
+dev.forgeos.adapter.spring.ForgeSpringAutoConfiguration

package/adapters/java-spring-boot-starter/target/classes/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -0,0 +1 @@
+dev.forgeos.adapter.spring.ForgeSpringAutoConfiguration

package/adapters/java-spring-boot-starter/target/maven-archiver/pom.properties

@@ -0,0 +1,3 @@
+artifactId=forge-java-spring-boot-starter
+groupId=dev.forgeos
+version=0.1.0-alpha.11

package/adapters/java-spring-boot-starter/target/maven-status/maven-compiler-plugin/compile/default-compile/createdFiles.lst

@@ -0,0 +1,6 @@
+dev/forgeos/adapter/spring/ForgeServiceBeanCondition.class
+dev/forgeos/adapter/spring/ForgeSpringRuntime.class
+dev/forgeos/adapter/spring/ForgeExternalService.class
+dev/forgeos/adapter/spring/ForgeSpringAutoConfiguration.class
+dev/forgeos/adapter/spring/ForgeQuery.class
+dev/forgeos/adapter/spring/ForgeCommand.class

package/adapters/java-spring-boot-starter/target/maven-status/maven-compiler-plugin/compile/default-compile/inputFiles.lst

@@ -0,0 +1,6 @@
+/home/runner/work/forge/forge/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeCommand.java
+/home/runner/work/forge/forge/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeExternalService.java
+/home/runner/work/forge/forge/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeQuery.java
+/home/runner/work/forge/forge/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeServiceBeanCondition.java
+/home/runner/work/forge/forge/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeSpringAutoConfiguration.java
+/home/runner/work/forge/forge/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeSpringRuntime.java

package/bin/forge.mjs

@@ -1,8 +1,26 @@
 #!/usr/bin/env node
 import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const args = process.argv.slice(2);
+
+if (args.includes("--version") || args.includes("-v")) {
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const version = typeof pkg.version === "string" ? pkg.version : "unknown";
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({
+      version,
+      cliVersion: version,
+      forgeosVersion: version,
+    }, null, 2));
+  } else {
+    console.log(version);
+  }
+  process.exit(0);
+}
+
 const entrypoint = join(root, "src", "forge", "cli", "main.ts");
 
 let register;

package/docs/changelog.md

@@ -0,0 +1,212 @@
+# Changelog
+
+Release history for the `forgeos` npm package.
+
+The canonical source file in the repository is `CHANGELOG.md`.
+
+## Unreleased
+
+## 0.1.0-alpha.19
+
+Alpha hardening:
+
+- Added the `agent-workroom` app template for Forge Studio style demos: external
+  agents edit the app, while ForgeOS shows preview URL, agent signals, check
+  runs, and handoff evidence through generated commands and liveQuery bindings.
+- Added `forge studio attach` for Studio-style observer apps: writes `.forge/studio/attachment.json`, prepares external-agent adapters/hooks, and returns the target preview URL.
+- Added `summary.preview` and `summary.urls.suggestedPreview` to `forge dev --once --json` so observer UIs can target the app under construction instead of pointing at themselves.
+- Improved `forge dev` port-busy failures with a `port_busy` JSON failure kind and suggested recovery commands, including the common "Is port X in use?" startup error shape.
+- `forge dev` now resolves the web app port before startup and automatically moves to the next available port when the default web port is busy, keeping the printed/JSON web URL truthful.
+- Improved `forge check --json` next actions by surfacing diagnostic-specific repair/inspect commands instead of a generic last-test-run repair hint.
+- Added `forge doctor agent --target <agent>` as the top-level agent readiness check.
+- Added explicit `forge agent ingest <source> --watch --file <events.ndjson>` support for opt-in hook/export file ingestion.
+- Added human-friendly verifier aliases: `forge verify quick`, `forge verify agent`, and `forge verify release`.
+- Made `forge status --human` an explicit accepted spelling and documented `forge add <npm-package> --workspace web` as the normal package-add path.
+- Made bare `forge inspect` default to the compact `summary` target instead of returning a usage error.
+- Added `forge release doctor`, `release check --allow-missing-local-release`, and `self-host check --prepared-only` so release readiness can distinguish hard failures from not-yet-prepared local artifacts.
+- Hardened the public packed-package smoke with dry-run mode, per-step JSON evidence, step timeouts, installed-global CLI coverage, hook smoke readiness, Studio open coverage, and preview-port cleanup checks.
+- Expanded `forge docs check` with YAML shape checks, internal Markdown link validation, optional ReadTheDocs-style venv installation, and strict MkDocs build execution.
+- Added authored-only review paths through `forge changed --authored` and `forge diff authored`, keeping generated artifacts collapsed unless explicitly requested.
+- Added `forge delta status --verbose --json` for schema, lock, path, and aggregate-count diagnostics without expanding the default status payload.
+- Added explicit hook readiness levels (`none`, `canary`, `trusted-native`) and documented `.codex/hooks.json` as versioned adapter configuration while keeping `.forge/agent/**` as local operational state.
+
+## 0.1.0-alpha.18
+
+Codex hook memory hardening:
+
+- Derived useful Codex hook metadata from the documented wire format while keeping raw prompts, tool inputs, tool responses, transcripts, and secrets out of Agent Memory.
+- Added safe command summaries, tool-call ids, result status, exit codes, response summaries, inferred files, and inferred runtime entries for Codex tool events.
+- Updated Codex hook installation with hook timeouts, status messages, and a local wrapper for checkout-based ingestion.
+- Updated Agent Memory docs and regression coverage for real Codex hook payloads.
+
+## 0.1.0-alpha.17
+
+External runtime timeline metadata:
+
+- Enriched `forge timeline` and `forge explain` for imported external runtimes.
+- External command/query calls now keep `service`, `language`, `risk`, `policy`, `tenantScoped`, and `needsApproval` metadata in DeltaDB.
+- Promoted this release on npm as both `alpha` and `latest`.
+
+## 0.1.0-alpha.16
+
+Stability alignment:
+
+- Fixed `forge timeline` and `forge explain` crashes after large generated artifact batches.
+- Fixed brownfield import detection for root-level Next.js App Router and Pages API routes.
+- Updated CLI, Agent Memory, and DeltaDB docs for the alpha.16 command surface.
+
+## 0.1.0-alpha.15
+
+Brownfield import analysis:
+
+- Added H49 `forge import analyze`, `forge import inspect`, and `forge inspect imported --json`.
+- Emits `.forge/import` inventory, route, frontend call, candidate entry, risk, migration plan, and imported agent contract artifacts.
+- Keeps every imported entry hidden from agents until review, with approval required for command-like or risky static detections.
+
+## 0.1.0-alpha.14
+
+Java and Nuxt/Vue support:
+
+- Added the Java external runtime adapter, Spring Boot starter, and `java-billing` conformance example.
+- Added generated Vue bindings and the `forgeos/vue` export.
+- Added Nuxt UI scaffolding through `forge make ui --framework nuxt`.
+- Updated docs, agent adapter guidance, generated manifests, and focused Java/Vue/Nuxt tests.
+
+## 0.1.0-alpha.13
+
+Agent Memory Bridge:
+
+- Added H48 redacted external agent event ingestion with normalized `forge.agent-event.v1` envelopes.
+- Added Codex and Claude Code hook installers plus Cursor MCP/rules setup.
+- Added `forge mcp serve`, `forge agent install`, `forge agent ingest`, `forge agent context`, and `forge agent memory`.
+- Persisted external agent activity in DeltaDB and linked agent/tool/file events into the semantic timeline.
+
+## 0.1.0-alpha.12
+
+Semantic Timeline:
+
+- Added the H47 DeltaDB semantic timeline projection with rebuildable events, entity indexes, causal edges, and projection state.
+- Upgraded `forge timeline` from raw operations into an entity-oriented timeline for runtime entries, policies, diagnostics, proofs, services, files, and sessions.
+- Added proof staleness detection and timeline context in `forge explain`.
+
+## 0.1.0-alpha.11
+
+Strict verify performance:
+
+- Reduced the validated `forge verify --strict` wall time from roughly 358-454s to about 116s on the current Windows test machine.
+- Added stable repo-local `tsx` CLI caching under `node_modules/.cache/forge-tsx-cli` so spawned CLI tests reuse the warm compiler path.
+- Balanced TestGraph strict execution across shared and isolated lanes, bringing the slowest files down from roughly 50s to under 10s in the updated profile.
+- Moved heavy refactor/impact/external runtime suites onto faster shared paths where safe and kept isolation for process-sensitive tests.
+- Documented and guarded the cache behavior so future test helpers preserve the speedup without checking cache contents into git.
+- Added guarded alpha release workflow support for promoting the public `latest` dist-tag when npm token auth is configured.
+
+## 0.1.0-alpha.10
+
+Launch polish:
+
+- Fixed `forge run <external-command> --args ...` so CLI arguments reach the external runtime bridge.
+- Added direct external query CLI support through `forge query <service.query> --args ...`.
+- Emit generated `.json` artifacts as pure JSON while keeping deterministic headers on code/text artifacts.
+- Relaxed the `minimal-web` template verify script to `forge verify --smoke` and added the missing `check` script to `b2b-support-web`.
+- Updated public protocol/changelog docs for the external runtime and Go adapter alpha line.
+- Bumped the create-app wrapper package line to `create-forgeos-app@0.1.0-alpha.4`.
+
+## 0.1.0-alpha.9
+
+Compiler, external runtime, and Go adapter:
+
+- Added the Forge external runtime protocol bridge for manifest-backed commands and queries.
+- Added the Go adapter MVP with a real `go-billing` conformance example.
+- Emitted external service metadata into inspect/API/agent artifacts, including `needsApproval` for agent tools.
+- Reuse compiler classifier package signals across export classification, dropping repeated package signal scans.
+- Reuse serialized graph JSON when rendering the largest generated TypeScript graph artifacts.
+- Keep generated Forge artifacts aligned with the `0.1.0-alpha.9` compiler/runtime version.
+
+## 0.1.0-alpha.8
+
+Publishing:
+
+- Publish prerelease packages through the ForgeOS alpha publisher so npm dist-tags stay aligned.
+
+## 0.1.0-alpha.7
+
+Publishing:
+
+- Keep npm prerelease publishing on the public alpha dist-tag.
+
+## 0.1.0-alpha.6
+
+Release and packaging hardening:
+
+- Added `forge --version` / `forge --version --json`.
+- Updated `create-forgeos-app` help to read the wrapper package version instead of a hardcoded string and bumped the wrapper to `0.1.0-alpha.2`.
+- Added dependency vulnerability evidence with an explicit waiver file and CI release gate.
+- Updated generated web template dependencies to current Vite/plugin-react and Next majors.
+
+## 0.1.0-alpha.5
+
+Release alignment for the public alpha channel:
+
+- Added `forge ai redteam --model-level --json` with deterministic prompt-injection, secret-exfiltration, approval-bypass, cross-tenant, and indirect tool-injection probes.
+- Added `forge security prove --full --json` support for source checkouts, with graceful structural-proof fallback when packaged apps do not include ForgeOS test fixtures.
+- Strengthened npm publish workflows to run `security prove --db postgres --full --json`.
+- Added public registry smoke coverage for `forgeos@alpha` and `create-forgeos-app@alpha`.
+- Bumped the create-app wrapper package line to `create-forgeos-app@0.1.0-alpha.1`.
+
+## 0.1.0-alpha.4
+
+Security assurance and release evidence hardening:
+
+- Added value-aware telemetry redaction for known secret values in safe-looking fields, messages, details, outputs, and stack traces.
+- Added webhook signature, timestamp, and replay protection helpers with Stripe/GitHub/generic HMAC coverage.
+- Added HTTP tenant-isolation tests that exercise the dev server/API boundary, not only the internal runtime executor.
+- Added `forge rls mutate-test --json` to kill dangerous generated RLS mutations such as missing FORCE RLS, missing policies, unconditional predicates, and `BYPASSRLS`.
+- Extended `forge security prove --json` with RLS mutation proof and invariant-level evidence metadata.
+- Added scripts to split security evidence by invariant and emit basic release supply-chain evidence plus CycloneDX SBOM.
+- Strengthened publish/security workflows so release gates use Postgres-backed security proof, RLS mutation proof, release evidence, and SBOM generation.
+
+## 0.1.0-alpha.3
+
+Native Forge AI agents on top of Vercel AI SDK v6:
+
+- Added `aiTool` and `agent` primitives with generated `agentTools.json` / `agentTools.md`.
+- Added `ctx.agent.run` and `ctx.ai.runAgent` using AI SDK `ToolLoopAgent`.
+- Added auto-tools for commands, queries, and liveQueries with read-only vs approval-required writes.
+- Added dev agent endpoints: `POST /ai/agents/run` and `POST /ai/agents/chat`.
+- Extended `forge ai` CLI with `tools`, `agents`, and `trace` subcommands.
+- Added `forge inspect agent-tools` and agent tool metadata in `agentContract.json`.
+- Upgraded runtime dependency to AI SDK v6 for tool calling, streaming UI, and MCP compatibility.
+
+Documentation:
+
+- Added public [AI](ai.md) page and AST-aware `rename command` codemod docs.
+- Full RTD expansion: [Agent Workflow](agent-workflow.md), [Frontend](frontend.md), [Security & Data](security-and-data.md), [Authoring](authoring.md), [Testing & Repair](testing-and-repair.md), [Self-Host](self-host.md), [Templates](templates.md), Material theme, search, and Mermaid diagrams.
+
+## 0.1.0-alpha.2
+
+Windows and generated-app hardening:
+
+- Fixed Node ESM handler loading on Windows by importing generated app modules through `file://` URLs across commands, queries, liveQueries, outbox actions, workflow steps, mocks, and telemetry adapters.
+- Fixed `forge dev` SSE streaming on the Node HTTP fallback so liveQuery snapshots are flushed immediately instead of buffering forever.
+- Hardened generated app scaffolding and web dev spawning on Windows.
+- Updated the B2B support template to route frontend imports through `web/lib/forge.ts` and use safer handler input validation.
+- Added focused tests for Node compatibility, template scaffolding, runtime imports, and streaming responses.
+- Added `create-forgeos-app@alpha` for `npm create forgeos-app@alpha`.
+- Added GitHub Packages mirror workflow for scoped package publishing.
+
+## 0.1.0-alpha.1
+
+Republish alpha with the dependency/API oracle improvements:
+
+- Added dependency API inspection commands for agents: `forge deps api`, `forge deps trace`, and `forge deps runtime-compat`.
+- Added dependency API summaries to `agentContract.json`.
+- Added package resolution traces, runtime compatibility metadata, and runtime/type mismatch diagnostics to `packageGraph`.
+- Reduced package graph warning noise for `package.json` metadata exports, declaration-file subpaths, and pattern exports.
+
+## 0.1.0-alpha.0
+
+Initial alpha packaging baseline for ForgeOS.
+
+This release line validates npm installation, the `forge` CLI binary, template creation, generated contracts, and the agent-native local development loop.
+
+Added Read the Docs-ready public documentation, generator/package version alignment checks, and a broad generated-app field-test harness for release hardening.

package/docs/forge-protocol.md

@@ -0,0 +1,189 @@
+# Forge External Runtime Protocol
+
+Forge apps can import and call services written outside TypeScript through a
+`forge.manifest.json` compatible manifest. The manifest is the source of truth
+for external commands and queries:
+
+- validate and import external service metadata;
+- expose external services in generated inspect/API/agent artifacts;
+- execute external commands and queries through the Forge runtime bridge.
+
+This lets Java/Spring, Go, Rust, C#, Python, and other runtimes join the Forge
+contract without requiring the Forge compiler to parse every language AST.
+
+## Manifest
+
+External services publish JSON that matches
+`schemas/forge-manifest.schema.json`.
+
+```json
+{
+  "forgeProtocol": "1.0",
+  "language": "java",
+  "framework": "spring-boot",
+  "service": {
+    "name": "billing",
+    "transport": "http",
+    "baseUrl": "http://localhost:8080",
+    "health": "/actuator/health"
+  },
+  "entries": [
+    {
+      "name": "createInvoice",
+      "kind": "command",
+      "path": "/invoices",
+      "policy": "billing.write",
+      "transaction": "external-managed",
+      "risk": "write",
+      "needsApproval": true,
+      "effects": ["invoice.created"]
+    },
+    {
+      "name": "listInvoices",
+      "kind": "query",
+      "path": "/invoices",
+      "policy": "billing.read",
+      "transaction": "read-only",
+      "risk": "read",
+      "tenantScoped": true
+    }
+  ]
+}
+```
+
+Queries must stay read-only. Commands can declare write, destructive, or
+external risk. Policies are metadata until the runtime bridge enforces them for
+the external transport.
+
+## CLI
+
+Validate a manifest:
+
+```bash
+forge manifest validate ./forge.manifest.json --json
+```
+
+Import or update a service in the app registry:
+
+```bash
+forge manifest import ./forge.manifest.json --json
+```
+
+Imports are stored in `.forge/external-manifests.json`. A root
+`forge.manifest.json` is also discovered automatically for single-service
+experiments.
+
+## Generated Artifacts
+
+After `forge generate`, external services are emitted to:
+
+- `src/forge/_generated/externalServices.json`
+- `src/forge/_generated/api.json` under `external`
+- `src/forge/_generated/agentContract.json`
+- `src/forge/_generated/agentTools.json`
+- `src/forge/_generated/capabilityMap.json`
+
+External auto-tools use `execution: "external-runtime-endpoint"`. Forge exposes
+runtime bridge endpoints for these tools:
+
+```text
+POST /external/:service/commands/:name
+POST /external/:service/queries/:name
+```
+
+The generated client exposes the same bridge through:
+
+```ts
+await client.externalCommand("billing.createInvoice", args);
+await client.externalQuery(api.external.queries["billing.listInvoices"], args);
+```
+
+Command entries can also be invoked from the CLI with a qualified external
+name:
+
+```bash
+forge run billing.createInvoice --args '{"title":"Invoice"}'
+forge query billing.listInvoices --args '{}'
+forge run query billing.listInvoices --args '{}'
+```
+
+## Java Adapter
+
+Forge ships a minimal Java adapter under `adapters/java`. The adapter is a small
+SDK for JVM services that want to join the Forge external runtime protocol
+without requiring Forge to parse Java source code.
+
+```java
+ForgeRegistry app = Forge.service("billing",
+    Forge.framework("java/jdk-http"),
+    Forge.baseUrl("http://127.0.0.1:8788"));
+
+app.command("createInvoice",
+    Forge.handle(CreateInvoiceInput.class, Billing::createInvoice),
+    Forge.policy("billing.manage"),
+    Forge.tenantScoped(true),
+    Forge.needsApproval(true));
+
+app.query("listInvoices",
+    Forge.handle(EmptyInput.class, Billing::listInvoices),
+    Forge.policy("billing.manage"),
+    Forge.tenantScoped(true),
+    Forge.readOnly());
+```
+
+The adapter exposes `GET /manifest`, `GET /health`, `POST /commands/:name`, and
+`POST /queries/:name`. The `examples/java-billing` app demonstrates manifest
+export, HTTP serving, policy enforcement through the Forge bridge, generated
+client calls, and agent tool registration.
+
+Spring Boot users can start from `adapters/java-spring-boot-starter`, which
+provides `@ForgeExternalService`, `@ForgeCommand`, and `@ForgeQuery` annotations
+plus a `ForgeRegistry` auto-configuration hook.
+
+## Runtime Bridge
+
+Forge accepts the normal JSON body:
+
+```json
+{ "args": {} }
+```
+
+For HTTP services, Forge forwards a JSON envelope:
+
+```json
+{
+  "args": {},
+  "auth": { "kind": "user", "userId": "u1", "tenantId": "t1", "role": "member" },
+  "forge": {
+    "service": "billing",
+    "entry": "createInvoice",
+    "kind": "command",
+    "traceId": "trace_..."
+  }
+}
+```
+
+Forge also forwards runtime headers such as `x-forge-trace-id`,
+`x-forge-auth-kind`, `x-forge-user-id`, `x-forge-tenant-id`, `x-forge-role`,
+and the inbound `Authorization` header when present.
+
+External services can return either a Forge envelope:
+
+```json
+{ "ok": true, "result": { "id": "inv_1" } }
+```
+
+or a raw JSON value, which Forge treats as the result for successful HTTP
+responses. Error envelopes should include `ok: false`, `diagnostics`, or
+`error`.
+
+Supported runtime transports:
+
+- `http`: calls `service.baseUrl + entry.path`.
+- `stdio`: starts `service.command`, writes the JSON envelope to stdin, and
+  reads a JSON envelope or raw JSON result from stdout.
+- `grpc`: accepted in manifests for forward compatibility, but not executable
+  by the built-in runtime bridge yet.
+
+Manifest `policy` values are added to Forge policy bindings during generation.
+Use a named Forge policy, or `public`, `user`, or `system`.

package/examples/go-billing/go.mod

@@ -0,0 +1,7 @@
+module github.com/Stahldavid/forge/examples/go-billing
+
+go 1.22
+
+require github.com/Stahldavid/forge/adapters/go v0.0.0
+
+replace github.com/Stahldavid/forge/adapters/go => ../../adapters/go