feat(mcp): add service endpoint directory and source adapters

.llm/runs/feat-openapi-mcp-endpoint-directory--s5/codex-thread-ids.md

@@ -0,0 +1,16 @@
+# openapi-mcp-endpoint-directory-s5-impl — Codex implementation thread
+- **Thread / session id:** `019fc9d0-5385-7710-ade4-a552ac9c9c10`
+- **Rollout:** `/home/codex/.codex/sessions/2026/08/04/rollout-2026-08-04T00-48-21-019fc9d0-5385-7710-ade4-a552ac9c9c10.jsonl`
+- **Worktree:** `/home/codex/repos/ns005-s5-impl`
+- **Branch:** `agent/openapi-mcp-endpoint-directory-s5` (NO upstream by design).
+- **Push rule:** explicit refspec only — `git push origin HEAD:refs/heads/feat/openapi-mcp-endpoint-directory`.
+- **Requested route:** provider=openai · model=gpt-5.6-sol · effort=high
+- **Observed route:** provider=openai · model=gpt-5.6-sol · effort=high
+- **Route verdict:** matched
+- **Runtime:** approval=never · sandbox=dangerFullAccess
+- **Brief (staged):** `/home/codex/openapi-mcp-endpoint-directory-s5-impl-brief.md`
+## Steering (same thread — never a second send-message-v2 at this worktree)
+```bash
+codex exec resume 019fc9d0-5385-7710-ade4-a552ac9c9c10 -- "<follow-up>"
+```
+_Written by `.llm/tools/agentic/codex/launch-codex-slice.ts`._

.llm/runs/feat-openapi-mcp-endpoint-directory--s5/context-pack.md

@@ -0,0 +1,103 @@
+# Context Pack: OMB S5 ServiceEndpointDirectoryPort + adapters
+
+## Run Metadata
+
+| Field | Value |
+| --- | --- |
+| Run ID | `feat-openapi-mcp-endpoint-directory--s5` |
+| Branch | `feat/openapi-mcp-endpoint-directory` |
+| Current phase | `implement` (plan locked via composed waiver) |
+| Archetype | `2 — Integration` slice |
+| Scope overlays | none |
+
+## Current State
+
+Research and design are locked at clean `origin/main` `2c8865e8c`. Slices 1–3 now implement the
+contract-first endpoint vocabulary, all four source adapters, deterministic composition, and the
+bounded spec-first identity probe, with the complete surface published and documented through both
+entrypoints. All implementation, consumer, JSR, and publish gates are green; supervisor evaluation
+and merge-readiness actions remain deliberately unstarted.
+
+## Completed
+
+- Read issue #1131, RFC #1123, epic context, P1/P3 verdicts, canonical discovery design, required
+  harness/doctrine/Aspire/JSR/PR/tooling authorities, and package consumers.
+- Confirmed baseline doc lint and publish dry-run clean, no lock churn.
+- Recorded Design checkpoint and the milestone-run PLAN-EVAL composed waiver.
+- Implemented discriminated source/directory/probe contracts and the named source precedence.
+- Implemented override, Aspire CLI, run-manifest, and appsettings sources with injected IO seams.
+- Proved 6/6 source fixtures, scoped check/lint/fmt, package-specific quality scan, and
+  `quality:gate` with no unsafe casts, lint ignores, or lock churn.
+- Implemented deterministic precedence/conflicts, exclusions before fetch, bounded concurrency,
+  row-local timeout/error isolation, and parent abort propagation.
+- Implemented credential-free, redirect-free OpenAPI-first probing, exact P3 401/403 guidance,
+  identity verification, response bounds, and opaque spec preservation.
+- Proved 12/12 endpoint tests, 78/78 package tests, and 79-file scoped check/lint/fmt.
+- Published the complete S5 surface from `.` and transitively `./cli`, documented default adapter
+  permissions/configuration, and regenerated the embedded README asset.
+- Proved zero full-export doc diagnostics, JSR audit exit 0, clean publish dry run, and no dependency
+  or lock churn. Grouping the adapters/port kept folder-cardinality debt at baseline.
+
+## In Progress
+
+- Implementation handoff after the Slice 3 commit/push/comment. The provided PR worktree remains
+  owned by the Desktop supervisor session; this attached thread remains the sole staging sender.
+
+## Next Steps
+
+1. Supervisor performs substantive review and the composed evaluation protocol.
+2. Supervisor decides when to update PR/issue acceptance state and mark the draft ready.
+3. Keep S6 projection/tool registration and S7 run-token producer wiring in their owned slices.
+
+## Key Decisions
+
+| Decision | Source | Notes |
+| --- | --- | --- |
+| `override > aspire-cli > run-manifest > appsettings` | P1 + RFC | CLI is primary live; explicit override remains supreme. |
+| Manifest requires expected current run id | plan D4 | Missing/mismatch is visible failure. |
+| No S4 imports | user coordinate rule | S6 composes later. |
+
+## Files Changed
+
+| Path | Status | Notes |
+| --- | --- | --- |
+| `.llm/runs/feat-openapi-mcp-endpoint-directory--s5/` | updated | Slice 1 evidence, reconcile note, attached-thread metadata |
+| `packages/mcp/src/ports/service-endpoint-directory-port.ts` | new | Discriminated contract and three consumed ports |
+| `packages/mcp/src/infrastructure/service-endpoints/` | new | Four named sources, URL policy, and fetch probe |
+| `packages/mcp/tests/service-endpoint-source*` | new | Aspire/source fixture matrix; 6/6 passing |
+| `packages/mcp/src/application/service-endpoint-directory.ts` | new | Default composition, precedence, bounds, isolation |
+| `packages/mcp/src/infrastructure/fetch-service-endpoint-probe.ts` | new | Spec-first identity probe and P3 mapping |
+| `packages/mcp/tests/service-endpoint-directory_test.ts` | new | Complete status/timeout/probe fixture matrix |
+| `packages/mcp/deno.json` | updated | Test-only write permission for existing temp-dir tests |
+| `packages/mcp/mod.ts`, `README.md` | updated | Published S5 surface and consumer/config/permission docs |
+| `packages/mcp/src/publish-assets.generated.ts` | updated | Regenerated embedded README corpus |
+
+## Gates
+
+| Gate family | Current status | Evidence |
+| --- | --- | --- |
+| Static | slices 1–3 PASS | 12 focused tests + 78 package tests + 79-file check/lint/fmt |
+| Fitness | slices 1–3 PASS | package quality scan + `quality:gate` + JSR audit |
+| Runtime | PASS | all source/status rows and hanging-row isolation fixture-proven |
+| Consumer | PASS | both entrypoints check/doc-lint clean; publish dry run clean |
+
+## Open Questions
+
+- None blocking implementation.
+
+## Drift and Debt
+
+- Drift: composed evaluator waiver; true remote baseline; manifest run-id injection clarification.
+- Drift: lint/fmt wrappers require the package config because the root workspace glob shape does not
+  parse for those Deno subcommands in this worktree; no source/config mutation was made.
+- Drift fixed: the package test task lacked the test-only write permission required by existing
+  temporary-directory tests; adding it restored the exact locked task to 78/78.
+- Drift fixed: flat owned files initially created a new infrastructure cardinality warning; the A2
+  port and adapters are now grouped under `src/ports/` and `infrastructure/service-endpoints/`.
+- Tooling note: the JSR helper counts Deno's neutral slow-type progress banner as a warning; raw doc
+  lint and publish show no actual slow-type diagnostic.
+- Debt: preserve existing `MCP-A6-V2-SHAPE`; no new debt planned.
+
+## Commits
+
+- See the draft PR's commit list + per-slice PR comments.

.llm/runs/feat-openapi-mcp-endpoint-directory--s5/drift.md

@@ -0,0 +1,150 @@
+# Drift Log: OMB S5 ServiceEndpointDirectoryPort + adapters
+
+Drift is append-only.
+
+## 2026-08-04 — Attached implementation uses a run-owned staging worktree
+
+- **What:** The canonical implementation lane runs in `/home/codex/repos/ns005-s5-impl` on local
+  branch `agent/openapi-mcp-endpoint-directory-s5`, then pushes each slice to the required PR ref.
+- **Source:** The agentic sender registry refused a rival sender because the provided worktree is
+  durably owned by the live Desktop supervisor thread.
+- **Expected:** The implementation lane would attach directly to the provided PR worktree.
+- **Actual:** A separate run-owned worktree preserves the one-sender invariant; the PR branch,
+  explicit push refspec, commit order, and review surface remain unchanged.
+- **Severity:** minor
+- **Action:** accept
+- **Evidence:** agentic launcher `duplicate_sender_risk`; implementation brief path/branch contract.
+
+## 2026-08-04 — Milestone evaluator composition replaces local formal PLAN-EVAL
+
+- **What:** No local formal PLAN-EVAL is launched; the plan gate is recorded as composed waiver.
+- **Source:** User-relayed `.llm/harness/workflow/milestone-run.md` evaluator rule and orchestrator D6.
+- **Expected:** Normal run-loop would require a separate local formal PLAN-EVAL.
+- **Actual:** Draft→ready augment + OpenHands + orchestrator pre-merge evaluation compose per-PR
+  evaluation; implementation proceeds in the same run after plan lock.
+- **Severity:** significant
+- **Action:** accept
+- **Evidence:** `supervisor.md`, `plan-eval.md`, `worklog.md` Plan Gate row.
+
+## 2026-08-04 — True baseline is fetched origin/main
+
+- **What:** Local `main` pointed to an older commit while this branch matched remote `main`.
+- **Source:** raw git rev-parse/fetch/ls-remote.
+- **Expected:** re-baseline against current `main`.
+- **Actual:** fetched `origin/main` is `2c8865e8c`; branch is identical and clean.
+- **Severity:** minor
+- **Action:** fix
+- **Evidence:** `research.md` re-baseline.
+
+## 2026-08-04 — Current manifest run id must be injected
+
+- **What:** S-8 says a manifest is eligible only when `runId` is current, but S5 has no independent
+  current-run token source; trusting the file's own token or wall clock would not prove currency.
+- **Source:** canonical discovery design vs P1 experiment/evidence and S7 ownership boundary.
+- **Expected:** identity binding `projectRoot + runId` before use.
+- **Actual:** S5 will require an expected current run id at composition. A present manifest without
+  it, or with a mismatch, reports a failed source outcome. S7 can wire the token later.
+- **Severity:** significant
+- **Action:** fix
+- **Evidence:** `research.md` finding 8/open-question resolution; `plan.md` D4.
+
+## 2026-08-04 — Scoped lint and format need the package config
+
+- **What:** The scoped lint/fmt wrappers failed before source analysis when Deno parsed the root
+  workspace glob entries; rerunning the same wrapper selections with
+  `--config packages/mcp/deno.json` passed with zero findings.
+- **Source:** Slice 1 validation output from `run-deno-lint.ts` and `run-deno-fmt.ts`.
+- **Expected:** The plan's wrapper commands would run from the repository root without an explicit
+  config.
+- **Actual:** `deno check` accepted the selection, while `deno lint`/`deno fmt` reported
+  `invalid type: string "packages/*", expected struct WorkspaceConfig` until the package config was
+  supplied.
+- **Severity:** minor
+- **Action:** accept for this lane; use the package config for exact lint/fmt evidence and leave root
+  configuration changes out of scope.
+- **Evidence:** `worklog.md` Slice 1 gate table; package-configured lint/fmt exit 0 over 76 files.
+
+## 2026-08-04 — Package test task omitted test-only write permission
+
+- **What:** The locked package-test command initially failed three pre-existing tests before their
+  assertions because they create temporary directories, while the task omitted `--allow-write`.
+- **Source:** Slice 2 `deno task --cwd packages/mcp test` output for `drift-evidence_test.ts` and
+  `stdio_test.ts`.
+- **Expected:** The package task would execute its complete test corpus and exit 0.
+- **Actual:** The task definition now grants write access only to the test process; runtime and
+  published package permissions are unchanged. The exact task then passed 78/78.
+- **Severity:** minor
+- **Action:** fix
+- **Evidence:** `packages/mcp/deno.json`; `worklog.md` Slice 2 package-test gate.
+
+## 2026-08-04 — A2 port and adapters grouped after cardinality audit
+
+- **What:** The Design file list described a flat domain contract and flat infrastructure adapters;
+  the first Slice 3 audit showed the five owned adapters would add a new `src/infrastructure`
+  cardinality warning and increase the inherited domain count.
+- **Source:** Archetype-2 port ownership plus F-16/R-FOLD-CARD and the Slice 3 JSR audit.
+- **Expected:** Preserve existing horizontal package debt without adding or deepening a violation.
+- **Actual:** The consumed contract lives in `src/ports/`; owned source/probe adapters and their URL
+  policy live in `src/infrastructure/service-endpoints/` without a sub-barrel. Public exports and
+  behavior are unchanged. Final audit restores inherited `src/domain` and
+  `src/application/flows` counts to their baseline 13 and introduces no infrastructure warning.
+- **Severity:** minor
+- **Action:** fix
+- **Evidence:** final JSR audit; zero-diagnostic scoped/doc gates in `worklog.md` Slice 3.
+
+## 2026-08-04 — JSR audit matches Deno's slow-type progress banner
+
+- **What:** `audit-jsr-package.ts` reports `slowTypeWarnings=1` because its `/slow type/i` matcher
+  captures Deno's neutral `Checking for slow types in the public API...` progress line.
+- **Source:** Slice 3 audit output and the helper's `runDryRun()` matcher.
+- **Expected:** Only an actual slow-type diagnostic would produce an audit warning.
+- **Actual:** Raw `deno doc --lint` for both entrypoints and `deno publish --dry-run --allow-dirty`
+  pass; Deno emits no slow-type error/warning after the progress line. The shared audit helper was
+  not changed by this package-scoped lane.
+- **Severity:** minor
+- **Action:** accept
+- **Evidence:** `worklog.md` Slice 3 doc/audit/publish rows.
+
+## 2026-08-04 — Fable review primary unavailable at provider
+
+- **What:** The canonical `review_codex_complex` primary could not start because the native provider
+  returned `model_not_found` for `fable-5` before review work or token use.
+- **Source:** Claude session `1abc6d8e-4c4a-4677-81dd-057eaab9145d` launch result.
+- **Expected:** Anthropic Fable 5 at medium effort performs the opposite-family substantive review.
+- **Actual:** The configured Claude-family Opus 4.8 fallback ran at medium effort in separate session
+  `a5d06fbf-041d-4d6a-a4d1-a69fce9ed447`; it returned PASS, then re-reviewed its three addressed
+  findings and retained PASS. Generator/evaluator family separation remained intact.
+- **Severity:** minor
+- **Action:** accept for this run; preserve both route identities in the review artifact.
+- **Evidence:** `review-codex-complex.md` §§1 and 6.
+
+## 2026-08-04 — OpenHands completion used the verdict artifact, not its stale status comment
+
+- **What:** The OpenHands workflow emitted an exact PASS verdict and committed `evaluate.md`, while
+  its earlier persistent status comment remained on `Running`; the workflow also did not emit the
+  optional trace directory.
+- **Source:** Agentic watcher result, PR comments, Actions run `30862805934`, and commit
+  `3e26b2bee`.
+- **Expected:** The persistent comment transitions to the terminal state and trace output accompanies
+  the evaluator artifact.
+- **Actual:** The later verdict comment and tracked evaluator artifact are terminal and internally
+  consistent; the stale progress comment and absent optional trace do not weaken acceptance proof.
+- **Severity:** minor
+- **Action:** accept for this run; use the exact watcher verdict, final PR comment, and tracked
+  `evaluate.md` as the authoritative evidence.
+- **Evidence:** https://github.com/rickylabs/netscript/pull/1194#issuecomment-5172905933;
+  `.llm/runs/feat-openapi-mcp-endpoint-directory--s5/evaluate.md`.
+
+## 2026-08-04 — Evaluator retained a stale identity-JSDoc advisory
+
+- **What:** OpenHands says `FetchServiceEndpointProbe` JSDoc does not repeat the root identity JSON
+  contract, but the reviewed source already documents that the root endpoint must return a JSON
+  `service` field matching the candidate name.
+- **Source:** `evaluate.md` finding F-3 compared with
+  `packages/mcp/src/infrastructure/service-endpoints/fetch-service-endpoint-probe.ts`.
+- **Expected:** The final evaluator narrative reflects the post-review source fix.
+- **Actual:** The advisory is factually stale but explicitly non-blocking; executable verification,
+  product behavior, and the PASS verdict are unaffected.
+- **Severity:** minor
+- **Action:** accept the immutable evaluator artifact and record the correction here.
+- **Evidence:** OpenHands PASS artifact; current `FetchServiceEndpointProbe` JSDoc.