@zakstam/codex-local-component 0.6.0 → 0.7.1

package/docs/HOST_INTEGRATION.md

@@ -0,0 +1,89 @@
+# Host Integration Guide
+
+Canonical default: runtime-owned host integration (`dispatchManaged: false`).
+
+This doc is aligned to the single canonical implementation in `../LLMS.md`.
+
+## Actor Scope Contract
+
+Use `actor: { userId?: string }` at all host/component boundaries.
+
+- `userId` present -> identified-user isolation.
+- `userId` omitted -> anonymous-only isolation.
+- Tenant/device identifiers are not part of the contract.
+
+## Required Flow
+
+1. Mount component in `convex/convex.config.ts`.
+2. Generate host wrappers from manifest (`pnpm run host:generate`).
+3. Keep host files split:
+- `convex/chat.generated.ts` (generated)
+- `convex/chat.extensions.ts` (app-owned)
+- `convex/chat.ts` (stable re-export entrypoint)
+4. Start runtime with `dispatchManaged: false`.
+5. Submit turns through `runtime.sendTurn(text)`.
+6. Run `chat.validateHostWiring` at startup.
+
+## Mount the Component
+
+```ts
+import { defineApp } from "convex/server";
+import codexLocal from "@zakstam/codex-local-component/convex.config";
+
+const app = defineApp();
+app.use(codexLocal);
+
+export default app;
+```
+
+Run `npx convex dev` once so `components.codexLocal.*` types are generated.
+
+## Generate and Check Host Surfaces
+
+```bash
+pnpm run host:generate
+pnpm run host:check
+```
+
+Generated wrappers use app `mutation(...)` and `query(...)` exports directly so Convex codegen and app-generated types stay authoritative.
+
+## Runtime Contract
+
+Runtime startup must be explicit runtime-owned:
+
+```ts
+await runtime.start({
+  actor,
+  sessionId,
+  dispatchManaged: false,
+  threadStrategy: "start",
+});
+```
+
+Turn start API for canonical flow:
+
+```ts
+await runtime.sendTurn(inputText);
+```
+
+## Startup Wiring Validation
+
+Call `chat.validateHostWiring` once when your host process starts.
+
+Expected response shape:
+
+- `ok: boolean`
+- `checks: Array<{ name: string; ok: boolean; detail?: string }>`
+
+If `ok` is `false`, fail startup and surface details in logs.
+
+## Convex Boundary Rule
+
+Convex-deployed code must not import `@zakstam/codex-local-component/protocol/parser`.
+Use host wrapper exports (`@zakstam/codex-local-component/host/convex`) inside Convex functions.
+
+## Advanced Appendix (Non-Default)
+
+Dispatch-managed orchestration is advanced and non-default. Use only when explicitly requested:
+
+- `DISPATCH_MANAGED_REFERENCE_HOST.md`

package/docs/HOST_PRESET_MATRIX.md

@@ -0,0 +1,72 @@
+<!-- AUTO-GENERATED by packages/codex-local-component/scripts/generate-host-surfaces.mjs -->
+
+# Host Preset Matrix
+
+Canonical source for host preset surfaces.
+
+## Presets
+
+| Preset builder | Profile | Ingest mode | Thread mode | Intended host |
+| --- | --- | --- | --- | --- |
+| `defineDispatchManagedHostSlice` | `dispatchManaged` | `mixed` | `resolve` | Tauri / externally claimed dispatch |
+| `defineRuntimeOwnedHostSlice` | `runtimeOwned` | `streamOnly` | `create` | Runtime-owned orchestration |
+
+## Deterministic query surface
+
+All focused preset builders include:
+
+- `validateHostWiring`
+- `getTurnDispatchState`
+- `getDispatchObservability`
+- `threadSnapshot`
+- `persistenceStats`
+- `durableHistoryStats`
+- `listThreadMessagesForHooks`
+- `listTurnMessagesForHooks`
+- `listPendingApprovalsForHooks`
+
+Additional query endpoints:
+
+- Dispatch-managed only: `listThreadReasoningForHooks`, `listPendingServerRequestsForHooks`
+- Runtime-owned only: `dataHygiene`
+
+## Deterministic mutation surface
+
+All focused preset builders include:
+
+- `ensureThread`
+- `enqueueTurnDispatch`
+- `claimNextTurnDispatch`
+- `markTurnDispatchStarted`
+- `markTurnDispatchCompleted`
+- `markTurnDispatchFailed`
+- `cancelTurnDispatch`
+- `ensureSession`
+- `ingestEvent`
+- `ingestBatch`
+- `respondApprovalForHooks`
+- `interruptTurnForHooks`
+
+Dispatch-managed additionally includes:
+
+- `upsertPendingServerRequestForHooks`
+- `resolvePendingServerRequestForHooks`
+
+## Wiring preflight
+
+Call `validateHostWiring` after deploy/startup to fail fast on component mount drift.
+
+Example:
+
+```ts
+await ctx.runQuery(api.chat.validateHostWiring, {
+  actor,
+});
+```
+
+Response shape:
+
+- `ok: boolean`
+- `checks: Array<{ name: string; ok: boolean; error?: string }>`
+
+If `ok` is false, one or more required `components.codexLocal.*` paths are not reachable in the current deployment.

package/docs/OPERATIONS_AND_ERRORS.md

@@ -0,0 +1,62 @@
+# Operations and Error Catalog
+
+Canonical default: runtime-owned host integration (`dispatchManaged: false`).
+
+This is an operations/runbook companion to `../LLMS.md`.
+
+## Runtime Boundary Errors
+
+- `E_RUNTIME_DISPATCH_MODE_REQUIRED`: runtime started without explicit dispatch mode.
+- `E_RUNTIME_DISPATCH_MODE_CONFLICT`: runtime API used in the wrong mode for current startup config.
+- `E_RUNTIME_DISPATCH_TURN_IN_FLIGHT`: attempted to start another turn while one is active.
+- `E_RUNTIME_DISPATCH_CLAIM_INVALID`: claimed-turn payload was invalid.
+
+## Authorization Errors
+
+- `E_AUTH_THREAD_FORBIDDEN`
+- `E_AUTH_TURN_FORBIDDEN`
+- `E_AUTH_SESSION_FORBIDDEN`
+
+## Sync Ingest Errors
+
+- `E_SYNC_EMPTY_BATCH`
+- `E_SYNC_SESSION_NOT_FOUND`
+- `E_SYNC_SESSION_THREAD_MISMATCH`
+- `E_SYNC_INVALID_CURSOR_RANGE`
+- `E_SYNC_OUT_OF_ORDER`
+- `E_SYNC_DUP_EVENT_IN_BATCH`
+
+Use `sync.ingestSafe` in host wrappers so recoverable conditions return structured status instead of hard-failing the loop.
+
+## Replay Recovery
+
+`sync.replay` and `sync.resumeReplay` are status-driven:
+
+- `ok`: replay served normally
+- `rebased`: requested cursor was behind retained window
+- `stale`: no useful replay window; rely on durable state and next checkpoint
+
+Follow `nextCheckpoints` and persist with `sync.upsertCheckpoint`.
+
+## Startup and Health Runbook
+
+1. Run `chat.validateHostWiring` at startup.
+2. Start runtime with `dispatchManaged: false`.
+3. Ensure one active turn at a time (`turnInFlight` guard).
+4. On protocol errors, restart bridge runtime and rebind session.
+5. On stale/missing session errors, call `sync.ensureSession` then continue ingest.
+
+## Pending Request Runbook
+
+When pending server requests accumulate:
+
+1. List pending requests.
+2. Confirm request id is still pending.
+3. Respond through the matching runtime response API.
+4. If turn already ended, treat request as expired.
+
+## Advanced Appendix (Non-Default)
+
+Dispatch-managed orchestration operations are documented separately:
+
+- `DISPATCH_MANAGED_REFERENCE_HOST.md`

package/docs/RUNTIME_OWNED_REFERENCE_HOST.md

@@ -0,0 +1,59 @@
+# Runtime-Owned Reference Host
+
+Canonical default: runtime-owned host integration (`dispatchManaged: false`).
+
+Use `../LLMS.md` for the normative implementation sequence.
+This file is a focused runtime-owned behavior reference.
+
+## Actor Scope Contract
+
+Use `actor: { userId?: string }` when starting runtime and calling host wrappers.
+Identified `userId` values are user-scoped; omitted `userId` is anonymous-scoped.
+
+## Runtime Mode
+
+```ts
+await runtime.start({
+  actor,
+  sessionId,
+  dispatchManaged: false,
+  threadStrategy: "start",
+});
+```
+
+In this mode:
+
+- `runtime.sendTurn(...)` starts turns.
+- `runtime.startClaimedTurn(...)` is invalid (`E_RUNTIME_DISPATCH_MODE_CONFLICT`).
+
+## Host Surface Expectations
+
+Runtime-owned generated wrappers include dispatch lifecycle, ingest/session, and hook query endpoints.
+Keep these files split:
+
+- `convex/chat.generated.ts` (generated preset surface)
+- `convex/chat.extensions.ts` (app-specific additions)
+- `convex/chat.ts` (stable re-export entrypoint)
+
+## Expected Progression
+
+Successful turn path:
+
+1. `sendTurn` accepted.
+2. Dispatch progresses through queue/claim/start.
+3. Runtime emits `turn/completed`.
+4. Dispatch terminal state is `completed`.
+
+Failure path:
+
+1. `sendTurn` accepted.
+2. Runtime emits failure event.
+3. Dispatch terminal state is `failed` with code/reason.
+
+Use `getDispatchObservability` for single-query diagnosis.
+
+## Advanced Appendix (Non-Default)
+
+If explicit external dispatch ownership is required, use:
+
+- `DISPATCH_MANAGED_REFERENCE_HOST.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakstam/codex-local-component",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -48,7 +48,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LLMS.md",
+    "docs"
   ],
   "publishConfig": {
     "access": "public",
@@ -75,10 +77,13 @@
     "clean": "rm -rf dist",
     "build": "tsc -p tsconfig.build.json",
     "build:watch": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "generate:host-surfaces": "pnpm run build && node ./scripts/generate-host-surfaces.mjs",
+    "check:host-surfaces": "pnpm run build && node ./scripts/generate-host-surfaces.mjs --check",
     "typecheck": "tsc --noEmit",
     "test": "pnpm run build && node --test test/*.test.mjs",
     "check:mount-imports": "node ./scripts/check-mount-imports.mjs",
     "check:unsafe-types": "node ./scripts/check-unsafe-types.mjs",
-    "ci": "pnpm run typecheck && pnpm run check:unsafe-types && pnpm run test && pnpm run check:mount-imports"
+    "check:docs:single-path": "node ./scripts/check-docs-single-path.mjs",
+    "ci": "pnpm run typecheck && pnpm run check:unsafe-types && pnpm run test && pnpm run check:mount-imports && pnpm run check:host-surfaces && pnpm run check:docs:single-path"
   }
 }