Next Work and Documentation Ownership

This page is the short, maintained backlog for the Context-Action architecture and tool-calling work. It prevents the semantic architecture guide, operational runbook, package READMEs, and generated API pages from carrying separate TODO lists.

Documentation ownership

Concern	Canonical source	Keep out of this source
Tool execution semantics, timeout, abort-drain, idempotency, durable recovery	Tool-calling Editor Architecture	deployment commands and incident response
Redis deployment, retention, rollback, and operator procedure	Durable Operation Runbook	new protocol semantics
Package API and consumer quickstart	package README.md	a second state-machine specification
Durable mutation execution, side-effect adapters, and backend operations	@context-action/tool-durable-operations and Durable Operation Runbook	provider-neutral tool schemas or domain outbox policy
Exported TypeScript signatures	TypeDoc output and typedoc-vitepress-sync	handwritten behavior claims
Symbol/document work context	@context-action/sem-doc reports and boundary guide	architecture-gate policy
Architecture evidence, snapshots, history, and ContextScope	Architecture Governance	operational work-context bindings
Short summaries	llmsData/ generated by llms-generator	manually edited backlog decisions

When a contract changes, update the owning source first, then the paired English/Korean page and generated artifacts. A package README should link to the owner instead of copying the full contract.

Mutation target inventory

The repository scan for the next side-effect adoption is intentionally explicit:

Surface	Classification	Durable mutation decision
OpenRouter /models and chat-completions calls	provider discovery/model inference; no Context-Action domain mutation	Do not wrap with the durable side-effect runner. Provider retry/timeout remains in the provider adapter.
Live Code Editor connected-folder save/delete	local filesystem mutation	Already uses the reference runner boundary in the standalone Bolt-style editor and the example editor.
Performance useApiRequest demo	generic GET/POST playground without an idempotency or inbox/outbox contract	Keep as a request caching/timeout example; it is not a production mutation target.
Queue publisher	no queue SDK or publisher is owned by this repository	Do not add a synthetic adapter. Select a real provider and document its acknowledgement/idempotency contract first.

This inventory prevents provider reads, model inference, and demo-only requests from being mistaken for production mutations. The next external-adapter task therefore requires an application owner, a real endpoint or queue, and a provider-owned idempotency/inbox-outbox contract before code is added here.

Completed baseline

• Durable operation records have lease-aware claim/replay/complete/fail/unknown transitions and revision-checked reconciliation.
• IndexedDB, Redis, and PostgreSQL reference backends, optional Redis client bridges, bounded keyset cleanup, Redis 7 integration checks, and a PostgreSQL 16 CI smoke path are available. Deployment preflight validates endpoint schemes without exposing credentials.
• Live Code Editor recovery covers both editor.saveFile and editor.saveAll. Multi-file recovery stores only a bounded digest/length manifest and leaves a mismatch in unknown rather than replaying the mutation.
• TOOL_EXECUTION_UNKNOWN diagnostics are retained in the durable record after sanitization so a resolver can inspect evidence without receiving source text.
• sem-doc remains the operational Symbol Context SSOT, while Architecture Governance remains the experimental authored-evidence/control-plane package.
• Complete symbol snapshots, commit history, context intersection, and explicit one-hop node_modules surface policy are documented as separate contracts.
• The tool-protocol/tool-durable-operations split is enforced by named Architecture Governance package-boundary rules; neither package may add the other's runtime dependency.
• The repository CI workflow uses Redis 7 and PostgreSQL 16 service containers for persistence smoke/integration checks; GitHub Environment deployment gates are intentionally outside this repository's CI/CD scope.
• A local tarball consumer smoke installs the unpublished tool packages and verifies their CJS exports; the registry-backed consumer check remains a publish-workflow gate.

Prioritized backlog

P0 — CI persistence contract (completed)

The repository CI test job starts Redis 7 and PostgreSQL 16 service containers and runs the public-API smoke checks, durable-operation integration suite, and HTTP/queue bridge fixtures. This proves the reference adapters and bridge contracts against real local servers in automation. It intentionally does not claim production endpoint, TLS, ACL, failover, migration, alert, or rollback evidence; those belong to the application deployment pipeline that owns the resources.

Acceptance: CI runs the checks without GitHub Environment secrets, failures remain visible in the normal test job, and no deployment workflow or second persistence abstraction is required.

P1 — external side-effect boundary (dedicated durable-operations package implemented)

The framework-neutral createDurableSideEffectRunner() contract is now implemented in @context-action/tool-durable-operations. It reuses the existing durable operation key and fingerprint, exposes explicit completed/failed/unknown outcomes, returns immediately when cancellation beats a draining handler, and supports domain-owned recovery. The standalone Bolt-style editor now adopts it for each connected-folder write/delete using a dedicated IndexedDB durable store. The package also exposes runHttpSideEffect() and runQueueSideEffect() as thin bridges over the same runner. Ambiguous records use the runner's existing recover() method. Both bridges require application-owned response or acknowledgement classifiers; they never guess that a non-2xx response or queue receipt is a completed/failed mutation. Production provider, queue, and HTTP integrations still need to adopt the corresponding bridge with provider-owned idempotency or inbox/outbox semantics. The inventory above confirms that no such target is currently owned by this repository. The local pnpm tool-durable:verify:http fixture additionally exercises the bridge through real fetch, an Idempotency-Key, an ambiguous response, and status-query recovery. The companion pnpm tool-durable:verify:queue fixture uses an ephemeral in-process publisher to model an authoritative acknowledgement and a lost acknowledgement after publish; it is deliberately not a queue SDK or production provider integration. Both are contract fixtures rather than production provider evidence.

The provider adapter admission checklist is now the required handoff artifact for selecting the first real HTTP or queue target; it records the owner, stable key scope, authoritative acknowledgement, reconciliation query, provider duplicate suppression, and rollback evidence before implementation begins.

Acceptance: the generic runner, HTTP bridge, and queue bridge tests plus the local HTTP and queue smoke fixtures cover duplicate delivery, a draining handler, provider/network ambiguity, known pre-send rejection, authoritative response or acknowledgement, and reconciliation. Each production adapter must add the same tests before it is considered complete. A retry with the same logical key cannot silently execute a second side effect. The browser filesystem integration is a reference boundary, not an exactly-once guarantee for File System Access API writes. The reference adapter now persists a stable destination-folder scope and includes it in the key; custom production filesystem adapters must expose the same scope contract.

P1 — SQL durable-operation adapter (PostgreSQL reference implemented)

createPostgresDurableOperationBackend() now maps the existing revision-checked claim/complete/fail/unknown contract to parameterized PostgreSQL conditional INSERT/UPDATE/DELETE statements. It keeps pg optional, exports an explicit schema migration string, and does not create a second state machine. The adapter decision and isolation contract are recorded in the PostgreSQL adapter decision.

Remaining acceptance: run pnpm tool-durable:verify:postgres with the production PostgreSQL version and pool wrapper, then record concurrent claims, lease reclaim, replay, unknown reconciliation, bounded retention, migration, isolation, and rollback evidence. A fake query-client test is not a live database verification.

P2 — execution provenance and operations

Sem-doc portion completed: sem-doc-work-context.v5, sem-doc-context-scope.v3, and sem-doc-context-scope-history.v2 now carry additive provenance for phase, logical owner, final state, configured timeout/output limits, measured output usage, and elapsed time. History commits share one aggregate budget, and strict parsing is centralized.

Tool-protocol portion completed: ToolCallEvent.provenance now carries a validated additive record for pending/final lifecycle state, logical owner, optional timeout/output budgets, measured UTF-8 output usage, and elapsed time. maxOutputBytes is enforced before a durable completion transition and returns TOOL_OUTPUT_LIMIT_EXCEEDED without retaining the result payload.

Shared policy implemented: @context-action/tool-protocol now exposes createToolObservabilityPolicy(), redactToolObservabilityValue(), and serializeToolObservabilityValue(). The policy bounds depth, collections, strings, and UTF-8 bytes; redacts credential/source-like fields; and exposes retention metadata without mutating the durable state machine. The Bolt-style trace adopts the same policy for displayed/copied details. The example live-editor and realtime web-coding trace projections retain only bounded metadata plus validated provenance; they deliberately drop the canonical request and result payloads. React durable-operation persistence now also projects ambiguous ToolCallResult diagnostics through sanitizeToolCallDiagnostic() and stores a stable code-based reason; known error records use the same projection, and successful terminal results remain lossless for replay.

Repository sink audit complete: Bolt UI details, example live-editor/web-coding metadata traces, and React durable unknown diagnostics now use bounded projections. The shared example trace store also enforces the policy's string bound and retention window; this is covered by pnpm --filter example verify:trace and the standalone trace verifier. The shared createToolObservationSink() adapter now gives application-owned provider/server sinks a serialized metadata-only record plus retention policy metadata and never forwards the raw ToolCallEvent. Remaining: an application owner must register the first external sink, choose its retention/deletion schedule, and provide a no-raw-request export check. This must not change the durable state transition contract.

Acceptance: sem-doc snapshots and tool-protocol lifecycle events produce validated records without credentials or raw source text; every production sink uses the shared bounded policy and has an owner, retention window, deletion path, and no-raw-request verification.

Next execution order

Use this order when turning the backlog into work. The order separates repository-ready work from items that require an environment owner or a product decision:

Order	Work	Exit evidence	Current status
1	Select and adopt the side-effect runner in the first real HTTP or queue mutation	Provider-owned idempotency/inbox-outbox contract plus duplicate, ambiguity, and recovery tests	Blocked on an application-owned endpoint/queue; repository scan found no production target
2	Close the external telemetry sink audit	Sink owner, effective retention/deletion job, createToolObservationSink() configuration, and no-raw-request check	Safe adapter is ready; external owner and deployment evidence remain
3	Verify the PostgreSQL adapter against the production SQL target	Versioned migration, actual pool wrapper, concurrent-claim integration output, isolation setting, owner, and rollback decision	Reference adapter and decision are implemented; live production verification remains

Do not open a second durable state machine while completing any of these items. A package change belongs in @context-action/tool-durable-operations; deployment and retention evidence belongs in the runbook; semantic behavior changes belong in the architecture guide.

Deferred, not active

• LSP-level exact reference locations, unsaved overlays, and CodeActions.
• A compiler-resolved graph provider such as @samchon/graph or @ttsc/graph.
• A renderer/visual bubble editor for ContextScope; the serialized scope and deterministic set operations come first.
• Provider-specific exactly-once guarantees without a provider-owned idempotency or inbox/outbox contract.

Handoff checklist

• [ ] Identify the owning package and canonical document before editing.
• [ ] Update the semantic guide or runbook, not both, unless the ownership table requires a cross-link.
• [ ] Add focused tests and record the contract/fixture version.
• [ ] Regenerate paired language and LLMS artifacts after source docs are stable.
• [ ] Run pnpm docs:management, focused package checks, and pnpm docs:build.