Merge pull request #218 from SNodeC/codex/phase-a1-0-typed-foundation

Establish Codex typed API foundation and operation contracts

Author: VolkerChristian

.gitattributes

@@ -0,0 +1 @@
+tools/codex/app-server-protocol-source/** -text linguist-vendored

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ on:
       - 'tests/**'
       - 'tools/**'
       - 'docs/ai/openai/codex/**'
-      - '.github/workflows/ci.yml'
+      - '.github/workflows/**'
   pull_request:
     paths:
       - 'CMakeLists.txt'
@@ -19,7 +19,7 @@ on:
       - 'tests/**'
       - 'tools/**'
       - 'docs/ai/openai/codex/**'
-      - '.github/workflows/ci.yml'
+      - '.github/workflows/**'
 
 jobs:
   gcc-debug:

cmake/Packing.cmake

@@ -65,6 +65,36 @@ set(CPACK_PACKAGE_VERSION_PATCH ${PROJECT_VERSION_PATCH})
 set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_SOURCE_DIR}/LICENSE")
 set(CPACK_RESOURCE_FILE_README "${CMAKE_SOURCE_DIR}/README.md")
 
+# Source packages are reproducibility artifacts, so they retain vendored
+# protocol evidence, schemas, fixtures, generators, tests, and documentation.
+# Keep local build products and execution-environment metadata out of those
+# archives. CPack's default ignore list does not exclude an in-tree build.
+set(
+    CPACK_SOURCE_IGNORE_FILES
+    "/CVS/"
+    "/\\.svn/"
+    "/\\.bzr/"
+    "/\\.hg/"
+    "/\\.git/"
+    "/\\.agents/"
+    "/\\.codex/"
+    "/\\.cache/"
+    "/\\.kdev4/"
+    "/\\.qtcreator/"
+    "/\\.vscode/"
+    "/_CPack_Packages/"
+    "/build[^/]*/"
+    "/softwipe_build/"
+    "/test1-cppcheck-build-dir/"
+    "/__pycache__/"
+    "\\.kdev4$"
+    "\\.py[cod]$"
+    "\\.swp$"
+    "\\.#"
+    "/#"
+    "~$"
+)
+
 set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
 set(CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS ON)
 set(CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS ON)

docs/ai/openai/codex/a1-typed-foundation.md

@@ -40,9 +40,25 @@ void setOnStateChanged(ai::openai::codex::Callbacks::StateChanged callback);
 void setOnDiagnostic(ai::openai::codex::Callbacks::DiagnosticReceived callback);
 
 ai::openai::codex::AppServerClient::RawProtocol& raw() noexcept;
+ai::openai::codex::typed::Client& typed() noexcept;
 std::optional<ai::openai::codex::InitializeResult> getInitializeResult() const;
 ```
 
+Const overloads are available for both `raw()` and `typed()`. Include
+`ai/openai/codex/typed/Client.h` when calling grouped typed accessors:
+
+```cpp
+client.typed().threads();
+client.typed().turns();
+client.typed().events();
+client.typed().requests();
+```
+
+`typed::Client` delegates to the four facade objects attached to the same raw
+protocol engine. The legacy direct `threads()`, `turns()`, `events()`, and
+`requests()` accessors remain deprecated source-compatible forwarders; no
+future domain facade is added directly to `AppServerClient`.
+
 The default constructor runs:
 
 ```text

docs/ai/openai/codex/app-server-client.md

@@ -23,7 +23,7 @@ contexts, JSONL framing, Qt, WebSocket, or browser code. In particular, a Unix
 socket path is not backend state. Concrete listener and framing code belongs in
 `src/apps/codex-backend`.
 
-## Phase A0 census boundary
+## Phase A0 census and A1 compatibility boundary
 
 Phase A0 pins the Codex CLI 0.144.6 stable and experimental App Server schemas
 and registers every mechanically discovered protocol entry in the private
@@ -40,6 +40,16 @@ commands and state transitions after A1 completes the typed App Server layer.
 Unknown and future input continues through the existing bounded extension
 records in the meantime.
 
+A1.0 migrates BackendCore to the grouped `client.typed()` accessors and adds no
+domain command or canonical-state meaning. A single production preservation
+helper converts typed-but-A2-unmodeled events into the existing
+`CodexExtensionReceived` path. It retains the surface identity, bounded raw
+payload, legacy optional decode error, and structured unknown-versus-malformed
+classification. Modeled events continue through their existing reducer cases.
+The structured classification is internal compatibility metadata; Frontend
+Protocol v1, its schema, snapshots, and remotely callable operations are
+unchanged.
+
 ## Ownership and construction
 
 `BackendCore<ClientT>` directly owns exactly one concrete client:
@@ -146,7 +156,9 @@ not create duplicate state.
 The default reducer retains 64 diagnostics and 64 Codex extensions.
 Individual diagnostic messages are capped at 16 KiB. Canonical extension
 records cap the method at 4 KiB, the serialized payload at 64 KiB, and a
-decoding error at 16 KiB. Model reroutes are capped at 64 per turn, and each
+decoding error at 16 KiB. Structured decode-diagnostic surface, field path, and
+message text use the corresponding method/error bounds and retain saturated
+original-size accounting when truncated. Model reroutes are capped at 64 per turn, and each
 accumulated item-content stream at 4 MiB. When accumulated content exceeds its bound, the reducer retains the
 newest suffix and increments `droppedContentBytes`. Snapshots expose both the
 dropped byte count and `contentTruncated`, so a consumer never mistakes a
@@ -187,8 +199,9 @@ valid location but no stable ID remains observable through the bounded
 `codex/item-without-id` extension fallback. Unknown events, or malformed future
 item events that cannot identify an owning thread and turn, remain observable
 as bounded `CodexExtensionReceived` records with their original method or
-deliberate extension name, payload, and optional decoding error. They do not
-fail the backend and are not silently discarded.
+deliberate extension name, payload, optional decoding error, and structured
+forward-compatibility or protocol-warning classification. They do not fail the
+backend and are not silently discarded.
 
 The immutable public snapshot retains the newest 64 extension records under
 stricter frontend-safe bounds: 1 KiB of UTF-8 method, 32 KiB of serialized

docs/ai/openai/codex/backend-core.md

@@ -10,14 +10,21 @@ Include `ai/openai/codex/typed/Client.h` and use the facades returned by an
 existing `AppServerClient`:
 
 ```cpp
-client.threads().start({.cwd = "/tmp/project"}, handler);
-client.threads().resume(threadId, {}, handler);
-client.threads().list({}, handler);
-client.threads().read(threadId, handler);
-client.turns().start(threadId, {typed::TextInput{"Hello"}}, {}, handler);
-client.turns().interrupt(threadId, turnId, handler);
+client.typed().threads().start({.cwd = "/tmp/project"}, handler);
+client.typed().threads().resume(threadId, {}, handler);
+client.typed().threads().list({}, handler);
+client.typed().threads().read(threadId, handler);
+client.typed().turns().start(threadId, {typed::TextInput{"Hello"}}, {}, handler);
+client.typed().turns().interrupt(threadId, turnId, handler);
 ```
 
+`typed::Client` is the installed, PIMPL-backed grouped facade. Its current
+accessors return the one existing `Threads`, `Turns`, `Events`, and `Requests`
+object owned by the `AppServerClient`; they do not allocate a second protocol
+engine. The old direct accessors remain source-compatible deprecated
+forwarders, for example `client.threads()` forwards to
+`client.typed().threads()`. New code should use the grouped form.
+
 Unsupported or newly introduced operations remain available through
 `client.raw()`.
 
@@ -37,13 +44,16 @@ including stability membership, lives in
 [coverage report](app-server-api-coverage.md) records inventory and
 implementation coverage as separate metrics. A private production
 `ProtocolSurfaceRegistry` is both the local disposition inventory checked by
-the coverage guard and the source used by runtime method and discriminator
-dispatch. Registration in that registry does not claim a typed implementation.
+the coverage guard and the source used by runtime method, top-level message,
+and implemented nested-union dispatch. A1.0 extends those same rows with
+offline authoritative request/result contracts, fixed domain slices, and
+mechanically derived completeness evidence. Registration alone still does not
+claim a typed implementation or schema completeness.
 
-This A0 census does not expand the typed API described below. Unimplemented
-entries remain raw- or opaque-preserved according to their runtime disposition.
-Adding the owner-frozen stable typed request, notification, server-request,
-item, and delta surface is A1 work.
+The grouped API described below remains the pre-A1 request surface plus the
+A1.0 cross-cutting error model. Other stable operations remain raw- or
+opaque-preserved according to their registry disposition until their fixed
+A1.1–A1.4 domain slice.
 
 The typed operation set is `thread/start`, `thread/resume`, `thread/list`,
 `thread/read`, `turn/start`, and `turn/interrupt`.
@@ -76,6 +86,16 @@ It also retains the client request ID and the original raw result JSON. A typed
 decode failure affects only that operation; it is not promoted to a transport
 or connection failure.
 
+For a remote JSON-RPC error, `remoteError` remains the authoritative raw
+`ProtocolError`, including its code, message, and optional data. When that
+data has the pinned `TurnError` shape, the adapter additionally exposes
+`codexErrorInfo` and `codexErrorDiagnostic`. Failure to decode this structured
+supplement never changes the remote-error classification or the connection.
+The placement is proven by pinned production source: the
+`ActiveTurnNotSteerable` handler serializes a `TurnError` and assigns it to the
+JSON-RPC error's `data`; the otherwise unconstrained data field is not decoded
+by name similarity.
+
 Submission failures are returned synchronously through the unchanged
 `RawProtocol::Submission` and do not invoke the completion. Accepted
 completions remain asynchronous. Typed adapters add neither a pending registry
@@ -87,8 +107,8 @@ handlers remain installed across an explicit stop/start.
 
 ## Events and items
 
-`client.events().setOnEvent()` receives an `Event` variant. The typed methods
-currently include:
+`client.typed().events().setOnEvent()` receives an `Event` variant. The typed
+methods currently include:
 
 - thread started and thread status changed;
 - turn started, completed, and failed completion classification;
@@ -118,6 +138,11 @@ complete `UserMessageItem::content` value held by the typed layer.
 completeness marker and any future string; an omitted marker has the
 schema-defined `full` default.
 
+The current public item union is named `ThreadItem`, with `Item` retained as a
+source-compatible alias. `ResponseItem` is deliberately a distinct public type
+direction; A1.0 does not combine its pinned alternatives with `ThreadItem` or
+invent the A1.1 alternatives.
+
 Unknown notification methods become `UnknownEvent`. Unknown item
 discriminators become `UnknownItem`. Unknown items retain any valid common item
 ID plus the thread and turn IDs supplied by their notification or parent turn.
@@ -126,9 +151,43 @@ A malformed item-local field also degrades to `UnknownItem` with a
 envelope becomes `UnknownEvent`. These values retain their original raw JSON
 and do not fail the connection.
 
+## Structured decode diagnostics and Codex errors
+
+Typed forward-compatibility handling has a structured diagnostic in addition
+to the temporarily retained optional string error:
+
+```cpp
+struct DecodeDiagnostic {
+    DecodeIssueKind kind;
+    DecodeIssueSeverity severity;
+    std::string surface;
+    std::string fieldPath;
+    std::string message;
+};
+```
+
+`UnknownMethod`, `UnknownDiscriminator`, and `UnknownEnumValue` use
+`ForwardCompatibility`. A known method or discriminator with an invalid
+payload uses `MalformedKnownPayload` and `ProtocolWarning`. Diagnostic text
+contains protocol identities and paths, not payload values; the complete raw
+JSON is retained separately. Neither class alone fails the connection.
+
+`CodexErrorInfo` has one public alternative for each of the 16 pinned known
+discriminators and an explicit `UnknownCodexErrorInfo` alternative. The four
+HTTP alternatives distinguish an omitted status from explicit `null` and a
+numeric value. `activeTurnNotSteerable.turnKind` is an open string-backed enum
+with helpers for `review` and `compact`; a future value remains typed and
+receives an `UnknownEnumValue` diagnostic. Every alternative retains its
+complete raw JSON.
+
+The `error` notification preserves its legacy raw `TurnError` JSON and adds a
+structured `TurnError` view. That view distinguishes omitted, null, and value
+semantics for `additionalDetails` and `codexErrorInfo`. Malformed known error
+payloads degrade to the raw-preserving compatibility path.
+
 ## Server requests
 
-`client.requests().setOnRequest()` currently classifies:
+`client.typed().requests().setOnRequest()` currently classifies:
 
 - `item/commandExecution/requestApproval`;
 - `item/fileChange/requestApproval`;
@@ -184,23 +243,25 @@ through the event loop.
 
 ## ABI and forward compatibility
 
-Task 3 adds public methods to `AppServerClient`, private implementation state,
-and new exported typed C++ classes. The `AppServerClient` object still
-contains only its existing `Impl` pointer, so its object layout is unchanged.
-`Protocol::ServerRequest` gains a `ServerRequestToken` field for occurrence
-ownership, which is a public raw-protocol type layout change. The library's
-normal C++ ABI/versioning policy applies to that change and to the new exported
-symbols and types.
+A1 is one deliberate in-progress C++ rebuild boundary. A1.0 adds
+`AppServerClient::typed()`, the one-pointer-PIMPL `typed::Client`, structured
+diagnostics, and public error variants. `AppServerClient` itself still contains
+only its existing `Impl` pointer; all grouped facades use the same raw engine.
+Public `std::variant` and aggregate layouts changed where the typed model
+required it, and this documentation does not claim binary compatibility for
+already-built consumers.
+
+SOVERSION remains unchanged in A1.0. The single A1 SOVERSION action is deferred
+to A1 closure in A1.4.
 
 Typed public headers are installed. Decoder headers under `detail/` remain
 private. Raw JSON on results, threads, turns, items, events, and server requests
 is the forward-compatibility escape hatch, and `client.raw()` remains
 available for protocol additions not yet represented by the typed layer.
 
-Adding `UserMessageItem` extends the public `Item` variant, and adding partial
-common metadata enlarges the public `UnknownItem` structure. Existing variant
-indices are retained and the new `UnknownItem` member is appended, preserving
-ordinary field access and existing three-field aggregate initializers at source
-level. The layouts are not binary-compatible, however, and exhaustive item
-visitors must handle the new alternative; already-built C++ consumers must be
-rebuilt.
+The legacy direct facade accessors remain available at source level with
+deprecation diagnostics. `Item` remains an alias of `ThreadItem`. Existing
+optional string decode errors remain while structured classification becomes
+authoritative. Raw JSON on results, threads, turns, items, events, server
+requests, and Codex error alternatives remains the escape hatch for protocol
+growth.