Creatidy/scarcity-router
5
0
Fork 0
Code Issues 13 Pull requests Projects Releases Packages Wiki Activity Actions

docs(architecture): execution-gateway program map, decisions and contracts (A0, issue #85) #96

Merged
adrian.tkacz merged 2 commits from docs/execution-gateway-a0 into develop 2026-09-19 17:10:00 +00:00
Conversation 3 Commits 2 Files changed 14 +1404 -101
kilo commented 2026-09-19 13:39:27 +00:00
Member
Copy link

Closes #85 (A0: architecture, decisions, and contracts for the optional execution gateway).

What this is

Documentation and contract work only — A0 of the execution-gateway program. No runtime behavior is implemented or changed. The goal is to make the architecture and contracts sufficiently explicit that M01–M10 (#86–#95) can proceed independently without inventing incompatible assumptions.

Analysis baseline: develop @ fce4311 (2026-09-19), as recorded in the issue.

Decisions recorded (docs/decisions.md)

Decision Effect
D-040 Two-mode product: optional execution gateway alongside unchanged recommendation-only default. Supersedes D-001 in part and D-017 (Ollama returns as an execution resource; the D-017 instability rationale becomes a design input). Owner-approved 2026-09-19.
D-041 Module architecture: logical module boundaries (not microservices), Resource State / Routing Core / Execution responsibility separation, one server + one native worker, minimal durable state (embedded SQLite-class store only), U-003 assigned to M01, current language/package structure preserved.
D-042 Route-decision contract separating physical model/variant, execution channel, entitlement, quota pool and client profile; frozen authorization precedence; profiles/aliases bind to the existing requirement model (no second scoring system, no LLM classifier); explicit targets are pinned, never silently replaced; recommendation → execution binding with no second routing decision; a recommendation is not a reservation.
D-043 Execution contracts: ingress request (capability-validated before inference), OpenAI compatibility matrix (PASS/PARTIAL/UNSUPPORTED/UNKNOWN, fail-closed), lifecycle rules (no backend swap after stream start, honest multi-call accounting, cancellation propagation), worker protocol (outbound TLS/WSS, versioned, no inbound port, no shell API), minimal audit-metadata field set with no prompt/response contents.
D-044 Security architecture of the server component (the explicit decision required by D-009/AGENTS.md for new network exposure, credential storage and write access): administrator/inference-client/worker identities, revocation, verified TLS (no verify=false), simple pairing bootstrap, bounded credential-store exception, admission limits, router-loop and SSRF protection, local-adapter isolation, logging/audit hygiene, single-user subscription scope.
D-045 Machine-interface coexistence: v1 untouched; OpenAI-compatible execution surface is a separately versioned contract whose /v1/ prefix is the OpenAI convention — disjoint path sets, separate error vocabularies; loopback REST adapter never becomes the execution server; parity requirement extended (amends D-028 non-goals; boundary notes on D-030/D-031).

Superseded/amended statuses updated in place on D-001, D-009, D-017, D-028, D-030, D-031 (pointers only; no history rewritten). Codex and ZCode execution uncertainties registered as U-012/U-013 (owned by M06/M07 Stage 1) rather than guessed.

Documents updated

  • docs/architecture.md — full A0 section: program map, operating modes/topologies, module responsibility table, separation invariants, server vs worker split, contract map (request, route decision, resource state, execution, worker protocol, entitlement/quota pools, compatibility matrix, audit), authorization precedence, recommendation-to-execution binding, durable state, coexistence, migration plan, existing-file → module mapping.
  • docs/product.md, docs/security.md (execution-gateway threat model covering every item of the issue's acceptance list), docs/machine-interfaces.md (coexistence + non-goals amendment), docs/providers.md (execution-adapter discipline), docs/capacity-model.md (observation classes, quota pools, promotions; v3 preserved), docs/selection-policy.md (route-decision inputs, precedence, pinned-target execution), docs/roadmap.md (program map), AGENTS.md (two-mode product boundary, security-invariant pointers), README.md (honest two-mode boundary text; gateway explicitly marked not-yet-implemented).

Continuation commit cb340e3 (2026-09-19, post-review coherence pass)

After the bounded review (PASS, see comment thread), a residual sweep for contradictory legacy wording outside the original 11 files found and fixed:

  • docs/llm-operating-policy.md — the "Project-specific overrides" section still asserted D-017 as the accepted override and the "Scarcity Router product boundary" section still carried the single-mode text; both rewritten to the two-mode product with D-017 explicitly marked superseded by D-040.
  • docs/competitive-landscape.md — differentiator text ("differs by not proxying or executing") rewritten to the two-mode framing (default recommendation-only; optional policy-gated gateway).
  • .kilo/rules/40-llm-operating-policy.md — agent rule summary still stated "D-017 excludes local inference"; updated to the D-040 supersession.
  • docs/architecture.md — review DEFER 2 resolved at the A0 level: the D-043 lifecycle now states fail-closed dispatch explicitly — the selected target is never silently replaced before or after stream start; automatic cross-target failover does not exist; the prompt-destination invariant holds from admission. M03 implements this; nothing is left to re-decide.
  • docs/decisions.md — review DEFER 1 resolved early: U-003's status line now points its deferred refresh/staleness remainder at M01 (#86) via D-041; plus the two cosmetic line-wrap splits (server-direct, backwards-compatibility) fixed.
  • docs/security.md — cosmetic line-wrap split (execution-gateway) fixed.

Deliberately left untouched: docs/history/* (historical archive), docs/m3-acceptance.md (milestone evidence record), scarcity_router/mcp.py docstrings and their tests (frozen v1 MCP surface, statements remain true), examples/agent-routing-prompt.md (describes the MCP recommendation flow, which stays recommendation-only), and all current-behavior tests asserting Ollama's absence from today's catalog/CLI (still true until M01/M04 implement executable resources).

Validation

uv sync --only-dev   # OK
make check           # 1045 tests OK
uv run basedpyright  # 0 errors, 0 warnings, 0 notes
git diff --check     # clean

Scope check: two commits (8f22c91, cb340e3), 14 documentation/rule files, no source/test/artifact changes, no merge commits; origin/develop..HEAD contains only this issue's change. Left open for human review; no merge.

Closes #85 (A0: architecture, decisions, and contracts for the optional execution gateway). ## What this is Documentation and contract work only — A0 of the execution-gateway program. **No runtime behavior is implemented or changed.** The goal is to make the architecture and contracts sufficiently explicit that M01–M10 (#86–#95) can proceed independently without inventing incompatible assumptions. Analysis baseline: `develop` @ `fce4311` (2026-09-19), as recorded in the issue. ## Decisions recorded (docs/decisions.md) | Decision | Effect | | --- | --- | | **D-040** | Two-mode product: optional execution gateway alongside unchanged recommendation-only default. Supersedes D-001 in part and D-017 (Ollama returns as an execution resource; the D-017 instability rationale becomes a design input). Owner-approved 2026-09-19. | | **D-041** | Module architecture: logical module boundaries (not microservices), Resource State / Routing Core / Execution responsibility separation, one server + one native worker, minimal durable state (embedded SQLite-class store only), U-003 assigned to M01, current language/package structure preserved. | | **D-042** | Route-decision contract separating physical model/variant, execution channel, entitlement, quota pool and client profile; frozen authorization precedence; profiles/aliases bind to the existing requirement model (no second scoring system, no LLM classifier); explicit targets are pinned, never silently replaced; recommendation → execution binding with no second routing decision; a recommendation is not a reservation. | | **D-043** | Execution contracts: ingress request (capability-validated before inference), OpenAI compatibility matrix (PASS/PARTIAL/UNSUPPORTED/UNKNOWN, fail-closed), lifecycle rules (no backend swap after stream start, honest multi-call accounting, cancellation propagation), worker protocol (outbound TLS/WSS, versioned, no inbound port, no shell API), minimal audit-metadata field set with no prompt/response contents. | | **D-044** | Security architecture of the server component (the explicit decision required by D-009/AGENTS.md for new network exposure, credential storage and write access): administrator/inference-client/worker identities, revocation, verified TLS (no `verify=false`), simple pairing bootstrap, bounded credential-store exception, admission limits, router-loop and SSRF protection, local-adapter isolation, logging/audit hygiene, single-user subscription scope. | | **D-045** | Machine-interface coexistence: v1 untouched; OpenAI-compatible execution surface is a separately versioned contract whose `/v1/` prefix is the OpenAI convention — disjoint path sets, separate error vocabularies; loopback REST adapter never becomes the execution server; parity requirement extended (amends D-028 non-goals; boundary notes on D-030/D-031). | Superseded/amended statuses updated in place on D-001, D-009, D-017, D-028, D-030, D-031 (pointers only; no history rewritten). Codex and ZCode execution uncertainties registered as **U-012/U-013** (owned by M06/M07 Stage 1) rather than guessed. ## Documents updated - `docs/architecture.md` — full A0 section: program map, operating modes/topologies, module responsibility table, separation invariants, server vs worker split, contract map (request, route decision, resource state, execution, worker protocol, entitlement/quota pools, compatibility matrix, audit), authorization precedence, recommendation-to-execution binding, durable state, coexistence, migration plan, existing-file → module mapping. - `docs/product.md`, `docs/security.md` (execution-gateway threat model covering every item of the issue's acceptance list), `docs/machine-interfaces.md` (coexistence + non-goals amendment), `docs/providers.md` (execution-adapter discipline), `docs/capacity-model.md` (observation classes, quota pools, promotions; v3 preserved), `docs/selection-policy.md` (route-decision inputs, precedence, pinned-target execution), `docs/roadmap.md` (program map), `AGENTS.md` (two-mode product boundary, security-invariant pointers), `README.md` (honest two-mode boundary text; gateway explicitly marked not-yet-implemented). ## Continuation commit `cb340e3` (2026-09-19, post-review coherence pass) After the bounded review (PASS, see comment thread), a residual sweep for contradictory legacy wording outside the original 11 files found and fixed: - `docs/llm-operating-policy.md` — the "Project-specific overrides" section still asserted D-017 as the accepted override and the "Scarcity Router product boundary" section still carried the single-mode text; both rewritten to the two-mode product with D-017 explicitly marked superseded by D-040. - `docs/competitive-landscape.md` — differentiator text ("differs by not proxying or executing") rewritten to the two-mode framing (default recommendation-only; optional policy-gated gateway). - `.kilo/rules/40-llm-operating-policy.md` — agent rule summary still stated "D-017 excludes local inference"; updated to the D-040 supersession. - `docs/architecture.md` — review DEFER 2 resolved at the A0 level: the D-043 lifecycle now states fail-closed dispatch explicitly — the selected target is never silently replaced before or after stream start; automatic cross-target failover does not exist; the prompt-destination invariant holds from admission. M03 implements this; nothing is left to re-decide. - `docs/decisions.md` — review DEFER 1 resolved early: U-003's status line now points its deferred refresh/staleness remainder at M01 (#86) via D-041; plus the two cosmetic line-wrap splits (`server-direct`, `backwards-compatibility`) fixed. - `docs/security.md` — cosmetic line-wrap split (`execution-gateway`) fixed. Deliberately left untouched: `docs/history/*` (historical archive), `docs/m3-acceptance.md` (milestone evidence record), `scarcity_router/mcp.py` docstrings and their tests (frozen v1 MCP surface, statements remain true), `examples/agent-routing-prompt.md` (describes the MCP recommendation flow, which stays recommendation-only), and all current-behavior tests asserting Ollama's absence from today's catalog/CLI (still true until M01/M04 implement executable resources). ## Validation ``` uv sync --only-dev # OK make check # 1045 tests OK uv run basedpyright # 0 errors, 0 warnings, 0 notes git diff --check # clean ``` Scope check: two commits (`8f22c91`, `cb340e3`), 14 documentation/rule files, no source/test/artifact changes, no merge commits; `origin/develop..HEAD` contains only this issue's change. Left open for human review; no merge.
Record the owner-approved two-mode product (D-040, superseding D-001 in
part and D-017) and specify the execution-gateway architecture so module
issues M01-M10 (#86-#95) can proceed independently: module map and
responsibility separation (D-041), route-decision contract with frozen
authorization precedence and entitlement/quota-pool semantics (D-042),
execution/worker/compatibility/audit contracts (D-043), server-component
security architecture and threat model (D-044, extending D-009), and
machine-interface coexistence with the separately versioned
OpenAI-compatible execution surface (D-045, amending D-028 non-goals;
D-030/D-031 boundary notes). Register Codex and ZCode uncertainties as
U-012/U-013 instead of guessing. Recommendation-only mode remains the
default with frozen contracts; no runtime behavior is implemented here.
kilo commented 2026-09-19 13:45:55 +00:00
Author
Member
Copy link

Bounded independent review — outcome (2026-09-19)

Frozen reviewed head: 8f22c91845049213e8bf28e2f1b7eee8a51f7782 (= PR head; unchanged during review). Reviewer scope: full fce4311..HEAD diff, issue #85 acceptance criteria, cross-document coherence (decision/module/issue references), security hygiene of the documents, scope discipline.

Verdict: PASS. No MERGE_BLOCKER findings; no remediation triggered under the bounded review lifecycle. Narrow final verification re-ran clean: reviewed head unchanged, working tree clean, basedpyright 0 errors, git diff --check clean.

DEFER findings (tracked for later work, not fixed here per lifecycle):

  1. U-003 forward pointer — docs/decisions.md U-003 still carries only its 2026-09-05 partial-resolution status; the assignment of its deferred remainder to M01 (#86) is recorded in D-041, docs/architecture.md and docs/capacity-model.md but not in the U-003 entry itself. One-line status update in a later PR (naturally M01/#86).
  2. Pre-stream failover wording — docs/security.md's absolute "prompt goes only to the selected authorized target" invariant vs the lifecycle rule's "backend never silently replaced after a response stream has started" leaves a seam an M03 implementer could misread as permitting pre-stream cross-target failover. The fail-closed reading (dispatch failure → explicit error, never silent re-dispatch to a different target; consistent with D-042's pinned-target rule) is the intended semantics — M03 (#88) should state it explicitly when implementing the execution contract.

Cosmetic non-finding (below the meaning threshold): three hyphen-at-line-end splits render with a spurious space (server- -direct in D-040/D-017 note, backwards- compatibility in D-045, execution- gateway in docs/security.md); fix opportunistically in a later documentation pass.

PR remains open for human review; no merge performed.

**Bounded independent review — outcome (2026-09-19)** Frozen reviewed head: `8f22c91845049213e8bf28e2f1b7eee8a51f7782` (= PR head; unchanged during review). Reviewer scope: full `fce4311..HEAD` diff, issue #85 acceptance criteria, cross-document coherence (decision/module/issue references), security hygiene of the documents, scope discipline. **Verdict: PASS.** No `MERGE_BLOCKER` findings; no remediation triggered under the bounded review lifecycle. Narrow final verification re-ran clean: reviewed head unchanged, working tree clean, `basedpyright` 0 errors, `git diff --check` clean. **DEFER findings (tracked for later work, not fixed here per lifecycle):** 1. **U-003 forward pointer** — `docs/decisions.md` U-003 still carries only its 2026-09-05 partial-resolution status; the assignment of its deferred remainder to M01 (#86) is recorded in D-041, `docs/architecture.md` and `docs/capacity-model.md` but not in the U-003 entry itself. One-line status update in a later PR (naturally M01/#86). 2. **Pre-stream failover wording** — `docs/security.md`'s absolute "prompt goes only to the selected authorized target" invariant vs the lifecycle rule's "backend never silently replaced *after a response stream has started*" leaves a seam an M03 implementer could misread as permitting pre-stream cross-target failover. The fail-closed reading (dispatch failure → explicit error, never silent re-dispatch to a different target; consistent with D-042's pinned-target rule) is the intended semantics — M03 (#88) should state it explicitly when implementing the execution contract. Cosmetic non-finding (below the meaning threshold): three hyphen-at-line-end splits render with a spurious space (`server- -direct` in D-040/D-017 note, `backwards- compatibility` in D-045, `execution- gateway` in `docs/security.md`); fix opportunistically in a later documentation pass. PR remains open for human review; no merge performed.
Continuation of the A0 documentation set on the reviewed head 8f22c91:

- rewrite the two remaining legacy product-boundary sections to the
  two-mode product (D-040): docs/llm-operating-policy.md project
  overrides (D-017 superseded) and product-boundary section,
  docs/competitive-landscape.md differentiator, and the .kilo rule
  summary
- state the fail-closed dispatch semantics explicitly in the D-043
  execution-contract lifecycle: no silent target replacement before or
  after stream start and no automatic cross-target failover (review
  DEFER 2)
- point U-003's deferred remainder at M01/D-041 in its own status line
  (review DEFER 1)
- fix three line-wrap splits that rendered with spurious spaces
  (server-direct, backwards-compatibility, execution-gateway)

No runtime behavior is implemented or changed; recommendation-only
operation remains the default and its frozen contracts untouched.

Validation: uv sync --only-dev; make check (1045 tests OK);
uv run basedpyright (0 errors); git diff --check clean.
kilo commented 2026-09-19 16:36:45 +00:00
Author
Member
Copy link

Continuation commit pushed: cb340e3 (2026-09-19)

Following the bounded review (PASS at frozen head 8f22c91), a fresh acceptance-criteria audit of issue #85 and a residual sweep for contradictory legacy product-boundary wording outside the original 11 files produced one documentation-only continuation commit. No runtime behavior was implemented or changed; recommendation-only operation remains the unchanged default.

What changed (6 files, docs/rules only):

  1. Legacy boundary wording resolved (in-scope product-boundary contradictions per #85's "no contradictory product-boundary rules" criterion):
    • docs/llm-operating-policy.md — "Project-specific overrides" no longer presents D-017 as the accepted override (now explicitly superseded by D-040, instability rationale retained as design input); the "Scarcity Router product boundary" section rewritten to the two-mode product, mirroring the updated AGENTS.md.
    • docs/competitive-landscape.md — differentiator no longer claims the product "does not proxy or execute"; reframed as default recommendation-only plus an optional policy-gated gateway under D-040.
    • .kilo/rules/40-llm-operating-policy.md — agent rule summary updated to the D-040 supersession.
  2. Review DEFER 2 resolved at the A0 level — docs/architecture.md D-043 lifecycle now states fail-closed dispatch explicitly: the selected target is never silently replaced before or after stream start; automatic cross-target failover does not exist; the docs/security.md prompt-destination invariant holds from admission, not from the first stream byte. M03 (#88) implements; nothing left to re-decide.
  3. Review DEFER 1 resolved early — docs/decisions.md U-003 status line now points its deferred refresh/staleness remainder at M01 (#86) via D-041 (one-line amendment; history preserved).
  4. Cosmetic review non-finding fixed — the three hyphen-at-line-end splits that rendered with spurious spaces (server-direct, backwards-compatibility, execution-gateway).

Deliberately untouched (with reasons): docs/history/* and docs/m3-acceptance.md (historical/acceptance records, never rewritten); scarcity_router/mcp.py docstrings + tests/test_mcp.py (frozen v1 MCP surface, statements remain true and are contract-asserted); examples/agent-routing-prompt.md (describes the MCP recommendation flow, which stays recommendation-only under the amended D-030/D-031); current-behavior tests asserting Ollama's absence from today's catalog/CLI (still true until M01/M04 land executable resources).

Acceptance-criteria audit result for #85: all seven criteria satisfied — decisions recorded with provenance (D-040…D-045, amendments in place, U-012/U-013 registered); no contradictory product-boundary rules remain in current documents (residual sweep re-run clean after this commit); architecture defines every module's responsibility/inputs/outputs/never-does with M01–M10 referenced; local CLI/app risks resolved to explicit M06/M07 Stage-1 evidence tasks; the threat model covers every listed item; the dependency graph is cycle-free with M06/M07 Stage 1 exempt; the program map links #86–#95. The issue's three "evidence still required" items are recorded as evidence requirements (worker transport and durable-state choices gated in M01/M05; compatibility-matrix evidence per adapter in M03/M06/M07), not invented.

Validation (re-run on cb340e3): uv sync --only-dev OK; make check 1045 tests OK; uv run basedpyright 0 errors/0 warnings/0 notes; git diff --check clean. origin/develop..HEAD = exactly the two #85 commits, no merge commits.

PR remains open for human review; no merge performed.

**Continuation commit pushed: `cb340e3` (2026-09-19)** Following the bounded review (PASS at frozen head `8f22c91`), a fresh acceptance-criteria audit of issue #85 and a residual sweep for contradictory legacy product-boundary wording outside the original 11 files produced one documentation-only continuation commit. No runtime behavior was implemented or changed; recommendation-only operation remains the unchanged default. **What changed (6 files, docs/rules only):** 1. **Legacy boundary wording resolved** (in-scope product-boundary contradictions per #85's "no contradictory product-boundary rules" criterion): - `docs/llm-operating-policy.md` — "Project-specific overrides" no longer presents D-017 as the accepted override (now explicitly superseded by D-040, instability rationale retained as design input); the "Scarcity Router product boundary" section rewritten to the two-mode product, mirroring the updated AGENTS.md. - `docs/competitive-landscape.md` — differentiator no longer claims the product "does not proxy or execute"; reframed as default recommendation-only plus an optional policy-gated gateway under D-040. - `.kilo/rules/40-llm-operating-policy.md` — agent rule summary updated to the D-040 supersession. 2. **Review DEFER 2 resolved at the A0 level** — `docs/architecture.md` D-043 lifecycle now states fail-closed dispatch explicitly: the selected target is never silently replaced before or after stream start; automatic cross-target failover does not exist; the `docs/security.md` prompt-destination invariant holds from admission, not from the first stream byte. M03 (#88) implements; nothing left to re-decide. 3. **Review DEFER 1 resolved early** — `docs/decisions.md` U-003 status line now points its deferred refresh/staleness remainder at M01 (#86) via D-041 (one-line amendment; history preserved). 4. **Cosmetic review non-finding fixed** — the three hyphen-at-line-end splits that rendered with spurious spaces (`server-direct`, `backwards-compatibility`, `execution-gateway`). **Deliberately untouched (with reasons):** `docs/history/*` and `docs/m3-acceptance.md` (historical/acceptance records, never rewritten); `scarcity_router/mcp.py` docstrings + `tests/test_mcp.py` (frozen v1 MCP surface, statements remain true and are contract-asserted); `examples/agent-routing-prompt.md` (describes the MCP recommendation flow, which stays recommendation-only under the amended D-030/D-031); current-behavior tests asserting Ollama's absence from today's catalog/CLI (still true until M01/M04 land executable resources). **Acceptance-criteria audit result for #85:** all seven criteria satisfied — decisions recorded with provenance (D-040…D-045, amendments in place, U-012/U-013 registered); no contradictory product-boundary rules remain in current documents (residual sweep re-run clean after this commit); architecture defines every module's responsibility/inputs/outputs/never-does with M01–M10 referenced; local CLI/app risks resolved to explicit M06/M07 Stage-1 evidence tasks; the threat model covers every listed item; the dependency graph is cycle-free with M06/M07 Stage 1 exempt; the program map links #86–#95. The issue's three "evidence still required" items are recorded as evidence requirements (worker transport and durable-state choices gated in M01/M05; compatibility-matrix evidence per adapter in M03/M06/M07), not invented. **Validation (re-run on `cb340e3`):** `uv sync --only-dev` OK; `make check` 1045 tests OK; `uv run basedpyright` 0 errors/0 warnings/0 notes; `git diff --check` clean. `origin/develop..HEAD` = exactly the two #85 commits, no merge commits. PR remains open for human review; no merge performed.
adrian.tkacz deleted branch docs/execution-gateway-a0 2026-09-19 17:10:00 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
adrian.tkacz
Labels
Clear labels   
accessibility
Barrier affecting people with disabilities

  
bug
Something isn't working

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
P1
Owner-declared highest explicit implementation priority (loop ordering rank)

  
P2
Required product and integration work

  
P3
Deferred or producer-dependent work

  
question
Further information is requested

  
wontfix
This will not be worked on

No labels
accessibility
bug
documentation
duplicate
enhancement
good first issue
help wanted
invalid
P1
P2
P3
question
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Creatidy/scarcity-router!96
No description provided.