Add structured results and OpenAI Realtime support

.github/workflows/ci.yml

@@ -28,7 +28,7 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
-      - name: Validate v0.2 source and release policy
+      - name: Validate v0.3 source and release policy
         run: |
           node scripts/release/check.mjs source
           node scripts/release/version.mjs self-test
@@ -50,7 +50,7 @@ jobs:
 
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
-          name: v0.2-archives-${{ github.sha }}
+          name: v0.3-archives-${{ github.sha }}
           path: ${{ runner.temp }}/release-archives
           if-no-files-found: error
 
@@ -65,7 +65,7 @@ jobs:
     steps:
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
-          name: v0.2-archives-${{ github.sha }}
+          name: v0.3-archives-${{ github.sha }}
           path: archives
 
       - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
@@ -88,8 +88,8 @@ jobs:
           await import("@full-self-browsing/concierge-react");
           await import("@full-self-browsing/concierge-svelte");
           assertSingleInstance();
-          if (CONTRACT_VERSION !== 2 || adapter.EXPECTED_CORE_CONTRACT_VERSION !== 2) {
-            throw new Error("contract v2 did not survive the packed install");
+          if (CONTRACT_VERSION !== 3 || adapter.EXPECTED_CORE_CONTRACT_VERSION !== 3) {
+            throw new Error("contract v3 did not survive the packed install");
           }
           NODE
 
@@ -111,7 +111,7 @@ jobs:
 
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
-          name: v0.2-archives-${{ github.sha }}
+          name: v0.3-archives-${{ github.sha }}
           path: archives
 
       - run: node scripts/release/compatibility.mjs "$(realpath archives)"
@@ -135,5 +135,6 @@ jobs:
           cache: pnpm
 
       - run: pnpm install --frozen-lockfile
+      - run: pnpm build
       - run: pnpm --filter @full-self-browsing/concierge-example-next-ai-sdk exec playwright install --with-deps chromium
       - run: pnpm --filter @full-self-browsing/concierge-example-next-ai-sdk exec playwright test --project=chromium

.github/workflows/release.yml

@@ -284,13 +284,13 @@ jobs:
             seal.runAttempt > Number(process.env.GITHUB_RUN_ATTEMPT) ||
             seal.sourceRef !== process.env.GITHUB_REF ||
             seal.outputArtifact !== process.env.RELEASE_OUTPUT_ARTIFACT ||
-            seal.distTag !== "latest" || seal.contractVersion !== 2
+            seal.distTag !== "latest" || seal.contractVersion !== 3
           ) throw new Error("release seal identity or digest drifted");
 
           const pinned = {
-            "config.mjs": "f6ecee16c34c1cf27b6f2eeee3701314c2b4324db152791111cecc6ab51299a7",
+            "config.mjs": "704e722e96934ac6f4534a28953e185aafd369713dd38f2964d3fa62523e10a4",
             "release-publisher.mjs": "a6757a8a8c5f4ef67ab6318e8f492844c6b100bf0f12051a6fd1d5b9bd9f0636",
-            "release-line.json": "06706bfef1b06028d3066a6e4b938df9ecfbaa196ea0bafba5ae39f1a32d3da0",
+            "release-line.json": "2fd76bdd314bfa509ede3a0e8b4a044c50fe556a1fcec015378986a2b6df899c",
           };
           const expected = ["release-seal.json"];
           for (const record of seal.tools) {

.release/lines/0.2.json → .release/lines/0.3.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "releaseLine": "0.2",
-  "contractVersion": 2,
-  "initialVersion": "0.2.0",
+  "releaseLine": "0.3",
+  "contractVersion": 3,
+  "initialVersion": "0.3.0",
   "distTag": "latest",
   "registry": "https://registry.npmjs.org/",
   "repository": "fullselfbrowsing/Concierge",

COMPATIBILITY.md

@@ -1,14 +1,14 @@
 # Compatibility
 
-Concierge 0.2 is a supported public preview. The three public packages form one
-fixed release set and share runtime contract v2.
+Concierge 0.3 is a supported public preview. The three public packages form one
+fixed release set and share runtime contract v3.
 
 ## Supported ranges
 
 | Component | Supported range | Release certification |
 | --- | --- | --- |
 | Node.js | `>=22.12.0` | 22.12 floor consumer and Node 24 CI/publisher |
-| `@full-self-browsing/concierge` | `^0.2.0` | Same patch as every adapter |
+| `@full-self-browsing/concierge` | `^0.3.0` | Same patch as every adapter |
 | React | `^18.2.0 || ^19.0.0` | 18.2 and 19.2 lines |
 | React DOM | `^18.2.0 || ^19.0.0` | Matches React |
 | Svelte | `^5.0.0` | 5.0 floor and current 5.56.9 |
@@ -21,7 +21,7 @@ the fixed package family has one runtime contract. Node 22.12 is the consumer
 floor; contributing with the pinned pnpm requires Node 22.13 or newer. Trusted
 npm publishing requires Node 22.14 or newer and uses Node 24.
 
-## AI SDK stacks certified for 0.2.0
+## AI SDK stacks certified for 0.3.0
 
 | Cell | `ai` | `@ai-sdk/react` | OpenRouter provider | Purpose |
 | --- | ---: | ---: | ---: | --- |
@@ -42,8 +42,10 @@ contract. Other AI SDK providers can consume the same `ToolSet`.
   to a fail-closed unavailable module under the browser condition.
 - `@full-self-browsing/concierge/ai-sdk/browser` needs WebCrypto. Its IndexedDB
   replay store additionally needs a browser IndexedDB implementation.
+- `@full-self-browsing/concierge/openai-realtime` is runtime-neutral and owns no
+  WebRTC, audio, credential, transcript, or network capability.
 - The full Next example declares the Node runtime. Edge deployment is not part
-  of the 0.2 support matrix.
+  of the 0.3 support matrix.
 - CommonJS output and `require()` are not supported. Use ESM imports.
 
 The release gate installs only the packed trio into foreign temporary
@@ -55,17 +57,19 @@ WebKit before the OIDC publish job can start.
 
 ## Version mixing
 
-Do not mix 0.1 and 0.2 packages. All adapters keep core as a peer dependency,
-and every runtime entry checks contract v2 before registration or dispatch.
+Do not mix contract-v2 and contract-v3 packages. All adapters keep core as a
+peer dependency, and every runtime entry checks contract v3 before registration
+or dispatch.
 Upgrade the trio and regenerate the lockfile together:
 
 ```sh
-pnpm up @full-self-browsing/concierge@^0.2 \
-  @full-self-browsing/concierge-react@^0.2 \
-  @full-self-browsing/concierge-svelte@^0.2
+pnpm up @full-self-browsing/concierge@^0.3 \
+  @full-self-browsing/concierge-react@^0.3 \
+  @full-self-browsing/concierge-svelte@^0.3
 
 pnpm why @full-self-browsing/concierge
 ```
 
 The final command should converge on one physical core version. See the
-[0.1-to-0.2 migration guide](./docs/migrations/0.1-to-0.2.md) for API changes.
+[0.2-to-0.3 migration guide](./docs/migrations/0.2-to-0.3.md) for API changes
+and backward-compatible adoption guidance.

CONTRIBUTING.md

@@ -69,11 +69,12 @@ Use a compound action and core's `workflow` controls for an application-owned
 sequence. Child calls must use stable step IDs. Do not put loops, delays, child
 dispatch, or cleanup orchestration in a framework or AI adapter.
 
-## Contract v2 changes
+## Contract v3 changes
 
-Contract v2 includes atomic `ResolvedCatalog` revisions, object-form dispatch,
-explicit terminal batch outcomes, dispatch lifecycle events, compound-action
-lineage, and the signed AI bridge's core dependencies.
+Contract v3 includes atomic `ResolvedCatalog` revisions, structured validated
+results, action-scoped bridge precedence, object-form dispatch, explicit
+terminal batch outcomes, lifecycle events, compound-action lineage, and the
+signed AI and OpenAI Realtime adapters' core dependencies.
 
 An additive implementation detail does not require a contract bump. A change
 that lets two versions disagree about bridge shape, revision capability,
@@ -85,7 +86,7 @@ or signed dispatch interpretation does. Contract changes require:
 3. mismatch mutations proving failure occurs before registration or dispatch;
 4. a migration guide and compatibility update.
 
-Contract v2 is fixed throughout `0.2.x`.
+Contract v3 is fixed throughout `0.3.x`.
 
 ## Tests and checks
 
@@ -142,7 +143,7 @@ adapter dependency. Core exposes AI SDK support only through explicit subpaths
 and keeps `ai` as the optional peer `^6.0.0 || ^7.0.0`.
 
 For a pre-1.0 minor transition only, commit a bounded old/new source range such
-as `workspace:^0.2.3 || ^0.3.0`. Never use `>=0.0.0`. The release versioner
+as `workspace:^0.3.3 || ^0.4.0`. Never use `>=0.0.0`. The release versioner
 validates that the second arm is the actual output and normalizes the Version
 Packages PR back to `workspace:^`, which pnpm packs as the new compatible minor.
 
@@ -156,7 +157,7 @@ created the code.
 
 Historical `.planning` evidence and `scripts/phase-09-*` reproduce the v0.1
 milestone and must not be rewritten as current release tooling. The live release
-contract is `.release/lines/0.2.json`, `scripts/release/`, and
+contract is `.release/lines/0.3.json`, `scripts/release/`, and
 `.github/workflows/release.yml`.
 
 ## Pull requests

HANDOFF.md

@@ -2,23 +2,26 @@
 
 ## Current state
 
-Concierge 0.2 is a supported-public-preview implementation built around runtime
-contract v2. The repository contains:
+Concierge 0.3 is a supported-public-preview implementation built around runtime
+contract v3. The repository contains:
 
 - a framework-neutral action catalog, atomic catalog revisions, direct and
   batch dispatch, consent, deduplication, cancellation, terminal control,
-  compound workflows, lifecycle observation, bridges, and sessions;
+  compound workflows, lifecycle observation, structured results,
+  action-scoped and stage-scoped bridges, and sessions;
 - React and Svelte lifecycle adapters that inject the same core instance and do
   no server-side registration;
 - an AI SDK 6/7 adapter with provider-neutral tools, strict call preparation,
   result correlation, and an ES256 signed server-to-browser dispatch bridge;
+- an app-owned OpenAI Realtime protocol codec for acknowledged catalogs,
+  completed calls, and correlated function-call output events;
 - a full Next App Router/OpenRouter example and the existing dual-framework SSR
   harness;
 - a version-neutral three-package release path with exact archives, independent
   sealing, OIDC trusted publishing, provenance verification, safe resumption,
   and the `latest` dist-tag.
 
-The public package set is one fixed trio at a shared `0.2.x` version:
+The public package set is one fixed trio at a shared `0.3.x` version:
 
 1. `@full-self-browsing/concierge`
 2. `@full-self-browsing/concierge-react`
@@ -33,7 +36,7 @@ the exact ceremony is in [RELEASING.md](./RELEASING.md).
 
 1. [README.md](./README.md) — public product and security promise.
 2. [COMPATIBILITY.md](./COMPATIBILITY.md) and [SUPPORT.md](./SUPPORT.md) — the
-   0.2 support contract.
+   0.3 support contract.
 3. [`packages/concierge/src/types.ts`](./packages/concierge/src/types.ts) — the
    runtime contract as code.
 4. [`packages/concierge/src/concierge.ts`](./packages/concierge/src/concierge.ts)
@@ -45,9 +48,9 @@ the exact ceremony is in [RELEASING.md](./RELEASING.md).
 7. [CONTRIBUTING.md](./CONTRIBUTING.md) — invariants and test expectations.
 8. [RELEASING.md](./RELEASING.md) — registry setup and protected release flow.
 
-Use `.planning/` when investigating how v0.1 decisions and evidence were
-derived. Its Phase 09 scripts and receipts are historical reproduction inputs,
-not the live 0.2 release authority.
+Use `.planning/` when investigating how earlier decisions and evidence were
+derived. Its phase scripts and receipts are historical reproduction inputs,
+not the live 0.3 release authority.
 
 ## Locked boundaries
 
@@ -68,7 +71,7 @@ not the live 0.2 release authority.
   envelope, replay consumption, and a live-catalog match.
 - Client consent, signed results, and client context are not server
   authorization.
-- All packages remain ESM-only and contract v2 throughout `0.2.x`.
+- All packages remain ESM-only and contract v3 throughout `0.3.x`.
 
 ## Signed bridge invariants
 
@@ -86,7 +89,7 @@ application-supplied stronger store.
 
 ## Live release authority
 
-- `.release/lines/0.2.json` — strict package set, contract, destination,
+- `.release/lines/0.3.json` — strict package set, contract, destination,
   compatibility, Node, and content-addressed npm identity.
 - `scripts/release/config.mjs` — strict parser and shared invariants.
 - `scripts/release/check.mjs` — source/workflow/fixed-trio gate.
@@ -128,9 +131,9 @@ three trusted-publisher records name `release.yml` plus `npm-production`.
 
 ## Known limitations
 
-- 0.2 is public preview, not a commercial-SLA release.
+- 0.3 is public preview, not a commercial-SLA release.
 - The signed bridge authenticates server admission of a browser batch; it does
   not authorize protected server effects or repair XSS.
-- Edge runtime is not in the 0.2 Next matrix.
+- Edge runtime is not in the 0.3 Next matrix.
 - Live model-provider calls are intentionally outside release authorization.
-- Only the latest 0.2 patch is maintained under [SUPPORT.md](./SUPPORT.md).
+- Only the latest 0.3 patch is maintained under [SUPPORT.md](./SUPPORT.md).

README.md

@@ -12,7 +12,7 @@ application retains control of validation, consent, execution, and results.
 [![npm](https://img.shields.io/npm/v/@full-self-browsing/concierge?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@full-self-browsing/concierge)
 ![Node](https://img.shields.io/badge/Node-%3E%3D22.12-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
 ![ESM](https://img.shields.io/badge/ESM-only-000000?style=for-the-badge)
-![Contract](https://img.shields.io/badge/runtime_contract-v2-1B998B?style=for-the-badge)
+![Contract](https://img.shields.io/badge/runtime_contract-v3-1B998B?style=for-the-badge)
 ![License](https://img.shields.io/badge/license-MIT-3DA639?style=for-the-badge)
 
 [![CI](https://img.shields.io/github/actions/workflow/status/fullselfbrowsing/Concierge/ci.yml?branch=main&style=flat-square&logo=github&label=CI)](https://github.com/fullselfbrowsing/Concierge/actions/workflows/ci.yml)
@@ -42,8 +42,9 @@ deduplication, workflow execution, and structured results. It does not own the
 model, chat interface, planning loop, authentication system, or server
 authorization policy.
 
-Version `0.2.1` is a supported public preview. The current release uses runtime
-contract v2 and ships as one synchronized set of three packages.
+Version `0.3.0` is a supported public preview. The current release uses runtime
+contract v3 and ships as one synchronized set of three packages. Existing
+data-less actions and stage-scoped bridges remain supported.
 
 ### Why Concierge
 
@@ -101,11 +102,11 @@ together so every adapter resolves the same physical core and contract version.
 | React and React DOM | `^18.2.0 || ^19.0.0` |
 | Svelte | `^5.0.0` |
 | AI SDK core | `^6.0.0 || ^7.0.0` |
-| Runtime contract | v2 throughout `0.2.x` |
+| Runtime contract | v3 throughout `0.3.x` |
 
 React and Svelte package roots are server-safe.
 Their runtime bindings live in `/client` and `/client.svelte`. Edge deployment
-is not part of the `0.2` support matrix. See [COMPATIBILITY.md](./COMPATIBILITY.md)
+is not part of the `0.3` support matrix. See [COMPATIBILITY.md](./COMPATIBILITY.md)
 for the full certified matrix and runtime boundaries.
 
 ## Install
@@ -119,14 +120,14 @@ pnpm add @full-self-browsing/concierge zod
 Add the matching framework adapter when needed:
 
 ```sh
-pnpm add @full-self-browsing/concierge@^0.2 \
-  @full-self-browsing/concierge-react@^0.2 \
+pnpm add @full-self-browsing/concierge@^0.3 \
+  @full-self-browsing/concierge-react@^0.3 \
   zod
 ```
 
 ```sh
-pnpm add @full-self-browsing/concierge@^0.2 \
-  @full-self-browsing/concierge-svelte@^0.2 \
+pnpm add @full-self-browsing/concierge@^0.3 \
+  @full-self-browsing/concierge-svelte@^0.3 \
   zod
 ```
 
@@ -208,6 +209,7 @@ For a complete model integration, continue with the
 | Svelte | `@full-self-browsing/concierge-svelte/client.svelte` | Provide the core instance with the Svelte snapshot normalizer and register bridges during initialization |
 | AI SDK | `@full-self-browsing/concierge/ai-sdk` | Convert a resolved catalog into model tools and correlate completed calls |
 | Signed server bridge | `/ai-sdk/server` and `/ai-sdk/browser` | Issue, verify, and dispatch short-lived browser batches |
+| OpenAI Realtime | `@full-self-browsing/concierge/openai-realtime` | Translate acknowledged catalogs, completed calls, and correlated output events without owning WebRTC |
 
 The React adapter includes `ConciergeActivityOverlay` for a configurable edge
 glow and optional “Powered by FSB” badge. Applications with their own activity
@@ -247,8 +249,12 @@ can consume the same `ToolSet`.
   terminal outcomes.
 * Compound actions use core-owned child dispatch, cleanup, delay, and bounded
   lineage.
+* Declared structured results are schema-validated, detached, recursively
+  frozen, bounded, and independently redacted for observers.
+* An action-scoped bridge takes precedence over its stage bridge; existing
+  stage fallback remains unchanged.
 * `onDispatch` receives redacted lifecycle events without controlling them.
-* Mixed `0.1` and `0.2` installations fail before bridge registration or
+* Mixed contract-v2 and contract-v3 installations fail before bridge registration or
   dispatch.
 
 ## Telemetry and privacy
@@ -270,7 +276,7 @@ stop-and-erase process.
 ## Security model
 
 The action catalog is a least-authority boundary, not an authentication system.
-Concierge does not authenticate users, and a client consent record is not
+Concierge does not authenticate a user, and a client consent record is not
 server authorization. A server that performs a protected effect must
 independently authenticate the current principal, authorize the exact action
 and payload under current policy, reject replay, and make the effect idempotent
@@ -288,9 +294,9 @@ public issue.
 
 ## Public preview and support
 
-The documented `0.2` surface is supported as a public preview. Patches do not
-intentionally break documented exports or contract v2 wire shapes. Only the
-latest `0.2.x` patch receives fixes.
+The documented `0.3` surface is supported as a public preview. Patches do not
+intentionally break documented exports or contract v3 wire shapes. Only the
+latest `0.3.x` patch receives fixes.
 
 A contract change, Node.js floor increase, removal of a documented export, or
 removal of AI SDK 6 or 7 support requires a synchronized minor release and a
@@ -305,10 +311,13 @@ and exclusions.
 | [React adapter](./packages/concierge-react/README.md) | Context, bridge registration, live state, and activity visuals |
 | [Svelte adapter](./packages/concierge-svelte/README.md) | Context, bridge registration, rune-aware snapshots, and lifecycle |
 | [AI SDK integration](./docs/integrations/ai-sdk.md) | Tool conversion, signed batches, result delivery, and deployment boundaries |
+| [Structured results](./docs/integrations/structured-results.md) | Output schemas, normalization, limits, and observer redaction |
+| [OpenAI Realtime](./docs/integrations/openai-realtime.md) | App-owned connection flow, catalog acknowledgements, batches, and output events |
 | [Next.js example](./examples/next-ai-sdk) | Complete AI SDK 7 application with the signed browser bridge |
 | [Compatibility](./COMPATIBILITY.md) | Certified versions, runtimes, framework boundaries, and version mixing |
 | [Telemetry privacy](./docs/privacy.md) | Data fields, local coordination, retention, opt-out, and erasure |
 | [Migration from 0.1](./docs/migrations/0.1-to-0.2.md) | Contract v2 and API migration guidance |
+| [Migration from 0.2](./docs/migrations/0.2-to-0.3.md) | Contract v3 upgrade and backward-compatible adoption guidance |
 | [Migration from a custom AI SDK adapter](./docs/migrations/custom-ai-sdk-to-concierge.md) | Adoption guidance for existing model tool integrations |
 | [Support policy](./SUPPORT.md) | Supported surface, maintenance window, and help channels |