feat(telemetry): query contract and Aspire adapter

[rickylabs]

Summary

Lands TEL-T7 as a contract-only telemetry query slice: @netscript/telemetry/query now exposes the read-side query contract, Standard Schema filter validators, and a thin Aspire dashboard HTTP adapter. Dashboard panels, UI integration, and data-layer switching remain out of scope.

Scope

• Archetype / area: ARCHETYPE-2 integration, packages/telemetry
• Closes [telemetry T7] @netscript/telemetry/query dashboard surface #408
• Part of epic: telemetry-revamp — framework telemetry convention + ports/adapters + dashboard query surface (Spine-1 enabler) #399

Definition of Done

• application/query contract compiles and is the single typed query seam. Evidence: wrapper check exit 0 (filesSelected=91, totalOccurrences=0); TelemetryQueryPort and query read models exported through @netscript/telemetry/query.
• No dashboard/UI code. Evidence: touched files are telemetry package source/tests plus harness artifacts only; no dashboard panels, routes, or UI files touched.
• adapters/aspire-query implements the contract against Aspire/OTLP, wrapping upstream Aspire dashboard HTTP endpoints. Evidence: AspireTelemetryQuery implements TelemetryQueryPort; focused tests pass 8/8 including trace grouping, logs/resources/metrics, API key/filter params, and absent-Aspire degradation.
• ./query subpath is exported and type-checks. Evidence: packages/telemetry/deno.json maps ./query to ./query.ts; wrapper check exit 0.
• ./query is doc-lint clean across the full export set. Evidence: deno task doc:lint --root packages/telemetry --pretty exit 0, summary totalErrors=0, ./query.ts total=0; raw full export deno doc --lint ... exit 0, Checked 11 files.
• deno publish --dry-run exits 0 without --allow-slow-types. Evidence: deno publish --dry-run --allow-dirty from packages/telemetry exit 0, dry run complete.
• Lock hygiene preserved. Evidence: deno.lock churn was reverted; final status clean after commit.
• E2E is not used as T7 evidence. Evidence: a malformed PR-comment command accidentally started deno task e2e:cli; it was interrupted immediately with Ctrl-C, exited 130, and is recorded in drift.md.

Slices

• T7 query contract + Aspire adapter - 5c965573

Validation

• deno run --allow-read --allow-run .llm/tools/run-deno-check.ts --root packages/telemetry --ext ts,tsx --pretty - exit 0; filesSelected=91; failedBatches=0; totalOccurrences=0.
• deno run --allow-read --allow-run .llm/tools/run-deno-lint.ts --root packages/telemetry --ext ts,tsx --pretty - exit 0; filesSelected=91; totalOccurrences=0.
• deno run --allow-read --allow-run .llm/tools/run-deno-fmt.ts --root packages/telemetry --ext ts,tsx --ignore-line-endings --pretty - exit 0; filesSelected=91; failedBatches=0; findings=0.
• deno test --allow-env --allow-read packages/telemetry/tests/query/aspire_query_test.ts packages/telemetry/tests/layering_test.ts - exit 0; 8 passed / 0 failed.
• deno task test from packages/telemetry - exit 0; 45 passed / 0 failed.
• deno task doc:lint --root packages/telemetry --pretty - exit 0; totalErrors=0; ./query.ts total=0.
• Raw full export deno doc --lint ./attributes.ts ./config.ts ./context.ts ./instrumentation.ts ./mod.ts ./orpc.ts ./query.ts ./registry.ts ./src/adapters/otel/mod.ts ./src/testing/mod.ts ./tracer.ts from packages/telemetry - exit 0; Checked 11 files.
• deno publish --dry-run --allow-dirty from packages/telemetry - exit 0; no --allow-slow-types; dry run complete.
• deno run --allow-read .llm/tools/fitness/check-doctrine.ts --root packages/telemetry --pretty - exit 0; FAIL=0; remaining WARN rows are pre-existing telemetry package debt.

Harness

• Run dir: .llm/runs/beta6-nondash--supervisor/
• Phase: impl
• Slice worklog: .llm/runs/beta6-nondash--supervisor/worklog-408.md
• Context pack: .llm/runs/beta6-nondash--supervisor/context-pack.md

Drift / Debt

• Drift recorded in .llm/runs/beta6-nondash--supervisor/drift.md:
  • branch lacked unsuffixed supervisor artifacts at slice start; prompt-supplied PLAN-EVAL PASS and scope fence treated as authoritative.
  • initial adapter file exceeded doctrine warning cap; split into adapter class + normalizer removed the new size warning.
• New debt: none.

[rickylabs]

[PHASE: IMPL] [VERDICT: LANDED]

TEL-T7 query contract + Aspire adapter landed for issue #408.

Slice

• Scope: contract-only @netscript/telemetry/query, application/query Standard Schema filters, TelemetryQueryPort, and thin adapters/aspire-query HTTP reader.
• Commit: 5c965573
• Out of scope honored: no dashboard panels, UI integration, or dashboard data-layer switching.

Gate Evidence

• Wrapper check: deno run --allow-read --allow-run .llm/tools/run-deno-check.ts --root packages/telemetry --ext ts,tsx --pretty - exit 0; filesSelected=91; failedBatches=0; totalOccurrences=0.
• Wrapper lint: deno run --allow-read --allow-run .llm/tools/run-deno-lint.ts --root packages/telemetry --ext ts,tsx --pretty - exit 0; filesSelected=91; totalOccurrences=0.
• Wrapper fmt: deno run --allow-read --allow-run .llm/tools/run-deno-fmt.ts --root packages/telemetry --ext ts,tsx --ignore-line-endings --pretty - exit 0; filesSelected=91; failedBatches=0; findings=0.
• Focused tests: deno test --allow-env --allow-read packages/telemetry/tests/query/aspire_query_test.ts packages/telemetry/tests/layering_test.ts - exit 0; 8 passed / 0 failed.
• Package tests: deno task test from packages/telemetry - exit 0; 45 passed / 0 failed.
• Full export doc-lint wrapper: deno task doc:lint --root packages/telemetry --pretty - exit 0; totalErrors=0; ./query.ts total=0.
• Raw full export doc-lint: deno doc --lint ./attributes.ts ./config.ts ./context.ts ./instrumentation.ts ./mod.ts ./orpc.ts ./query.ts ./registry.ts ./src/adapters/otel/mod.ts ./src/testing/mod.ts ./tracer.ts from packages/telemetry - exit 0; Checked 11 files.
• Publish dry-run: deno publish --dry-run --allow-dirty from packages/telemetry - exit 0; no --allow-slow-types; dry run complete.
• Doctrine fitness: deno run --allow-read .llm/tools/fitness/check-doctrine.ts --root packages/telemetry --pretty - exit 0; FAIL=0; remaining WARN rows are pre-existing telemetry package debt.

Command Note

• A malformed first PR-comment command interpreted Markdown backticks in the shell and accidentally started deno task e2e:cli; it was interrupted immediately with Ctrl-C and exited 130. No E2E verdict was produced or used as evidence; this is recorded in drift.md.

Harness Artifacts

• Worklog: .llm/runs/beta6-nondash--supervisor/worklog-408.md
• Context pack: .llm/runs/beta6-nondash--supervisor/context-pack.md
• Drift: .llm/runs/beta6-nondash--supervisor/drift.md

[rickylabs]

@openhands-agent model=openrouter/qwen/qwen3.7-max provider=openrouter output=pr-comment iterations=800

use harness

IMPL-EVAL — TEL-T7 query contract + aspire-query adapter + ./query subpath (issue #408, PR #567)

You are the IMPL-EVAL evaluator (separate session from the Tier-D generator) for one slice of the
beta6-nondash--supervisor harness run. Branch feat/408-telemetry-t7-query, TRUE base c8f68721,
slice commit 5c965573. Read-only. Run the cheapest decisive checks FIRST, form a verdict, POST
it, then spend remaining budget.

SKILL

• netscript-harness — IMPL-EVAL protocol, verdict-definitions.md, Concept of Done.
• netscript-doctrine — @netscript/telemetry ARCHETYPE-2; the application/ vs adapters/
  boundary, public-surface/subpath-export rules (a ./query subpath must be in the export map +
  deno.json). [telemetry T1] Framework telemetry convention (TC-1..14) + attribute-namespacing law #402 convention governs any surfaced attribute/semconv names.
• netscript-tools — scoped run-deno-* wrappers are the ONLY gate-evidence source.
• netscript-deno-toolchain — full-export deno doc --lint is the gate:jsr bar (not mod.ts
  alone); deno publish --dry-run WITHOUT --allow-slow-types.
• netscript-pr — merge close-gate (process: gate issue closure on verified acceptance (stop false-closed acceptance) #387): gate = [telemetry T7] @netscript/telemetry/query dashboard surface #408 acceptance + gate: boxes checked with
  evidence. Report any unchecked box.

DECISIVE CHECKS — in order; POST verdict after check 4

1. SCOPE FENCE held (D-6; core). T7 is contract + aspire-query adapter ONLY. Confirm the diff
   ships NO dashboard-panel / UI / rendering code — only application/query contract, an
   adapters/aspire-query adapter, and the ./query subpath. Any panel/UI wiring is scope creep →
   FAIL_RESCOPE. (A dashboard-coupling question recorded in drift instead of implemented is
   correct, not a gap.)
2. Contract soundness. application/query is a typed/Standard-Schema query contract (the single
   query seam); adapters/aspire-query implements it against Aspire/OTLP by wrapping upstream
   APIs, not reinventing. A local re-implementation of OTLP querying → FAIL_FIX.
3. ./query subpath surface. The subpath is declared in the package export map + deno.json,
   type-checks, and is deno doc --lint-clean across the FULL export set (verify ./query.ts is
   in the linted set with total=0); deno publish --dry-run (no --allow-slow-types) exit 0.
4. Gates + hygiene (decisive). Reproduce via scoped wrappers on packages/telemetry:
   check/lint/fmt exit 0; focused tests green; git diff c8f68721..HEAD -- deno.lock EMPTY; no as
   casts beyond the 2 accepted (any new cast → FAIL_FIX). Note: the generator hit a gh pr comment
   backtick landmine that briefly started e2e:cli (Ctrl-C, exit 130) — that run is NOT evidence and
   is logged in drift; ignore it. → FORM VERDICT AND POST THE PR COMMENT NOW.
5. (If budget remains) Confirm the aspire-query adapter tests exercise a real contract round-trip.

Rules

• Read-only. NEVER mutate deno.lock (git checkout -- deno.lock first). TRUE base c8f68721.
• Write verdict to .llm/runs/beta6-nondash--supervisor/evaluate-408.md, commit to THIS PR branch,
  POST the PR comment. End both with the undecorated first-token line:
  OPENHANDS_VERDICT: PASS / FAIL_FIX / FAIL_RESCOPE / FAIL_DEBT.

---

OUTPUT CONTRACT (mandatory — verdict first)

1. Post the verdict PR comment IMMEDIATELY after you form the verdict — BEFORE any
   optional deep-dive, extra verification, or long context dump. Iteration budgets
   exhaust; a verdict comment deferred to the end of the run is frequently lost.
2. That PR comment MUST start with the formal header line, exactly:
   [PHASE: ] [VERDICT: ]
   where is your eval phase (e.g. IMPL-EVAL, PLAN-EVAL) and is one
   of PASS, FAIL_FIX, FAIL_RESCOPE, FAIL_DEBT, FAIL_PLAN.
3. ALWAYS end BOTH the verdict PR comment AND your summary file with one final
   machine-readable line of the exact form:
   OPENHANDS_VERDICT:
   using a literal token from: PASS, FAIL_FIX, FAIL_RESCOPE, FAIL_DEBT, FAIL_PLAN,
   NONE. Use NONE only when no verdict could be reached.

[rickylabs]

OpenHands Agent — Completed

OPENHANDS_VERDICT: PASS

Model: openrouter/qwen/qwen3.7-max
Provider: OPENROUTER
Job status: success
Verdict source: summary-file
Verdict comment: #567 (comment)
Summary source: agent
Housekeeping: ack=success trace=success commit-artifacts=success replies=skipped draft-pr=skipped
Trace: .llm/tmp/run/openhands/pr-567/run-28903913431-1 (in the Actions artifact)
Artifact: openhands-agent-28903913431-1

IMPL-EVAL Summary — TEL-T7 query contract + aspire-query adapter

Summary

Evaluated PR #567 (feat/408-telemetry-t7-query, slice 5c965573 on base c8f68721) for the
@netscript/telemetry query contract + Aspire adapter landing. All four decisive checks pass;
bonus check 5 (adapter test round-trip) also confirmed with remaining budget.

Changes Verified

• packages/telemetry/src/application/query/ — contract (schema.ts, types.ts, mod.ts)
• packages/telemetry/src/adapters/aspire-query/ — adapter (aspire-telemetry-query.ts, aspire-telemetry-normalize.ts, mod.ts)
• packages/telemetry/src/domain/query.ts — primitive domain types
• packages/telemetry/src/ports/telemetry-query-port.ts — read-side query port
• packages/telemetry/query.ts — subpath entry point
• packages/telemetry/deno.json — export map + subpath declaration
• packages/telemetry/README.md — subpath table update
• packages/telemetry/tests/query/aspire_query_test.ts — adapter tests
• packages/telemetry/tests/layering_test.ts — aspire-query import guard added

Validation

Gate	Result
Scope fence (D-6)	Pass — zero panel/UI/rendering code
Contract soundness	Pass — Standard-Schema typed, adapter wraps Aspire HTTP APIs
./query subpath	Pass — declared, type-checks, doc-lint clean, publish dry-run exit 0
deno check (91 ts/tsx)	exit 0
deno lint (91 ts/tsx)	exit 0
deno fmt --check (91 ts/tsx)	exit 0
deno test --filter telemetry	45 passed, 0 failed
deno doc --lint	exit 0 across all 11 exports
deno publish --dry-run (no --allow-slow-types)	exit 0
Lock diff (c8f6872..5c96557)	Empty
New as casts	0 (only JSDoc prose)
Adapter test round-trip	Pass

Responses

N/A — first IMPL-EVAL pass for this slice.

Remaining risks

• README.md markdown table alignment drift flagged only by full-package deno fmt --check on Markdown files — cosmetic, does not block merge. Could be addressed in a follow-up formatting sweep.
• @tanstack/ai-anthropic/@tanstack/ai-openai peer-dependency on zod@^4.0.0 (resolved 3.25.76) exists at workspace level — pre-existing, unrelated to T7.

OPENHANDS_VERDICT: PASS

Run: https://github.com/rickylabs/netscript/actions/runs/28903913431

[rickylabs]

[PHASE: IMPL-EVAL] [VERDICT: PASS]

IMPL-EVAL: TEL-T7 query contract + aspire-query adapter + ./query subpath

PR: #567 | Base: c8f6872 | Slice: 5c96557

---

Decisive Checks

✅ Check 1 — SCOPE FENCE (D-6)

Pass. Diff contains ONLY: application/query contract, adapters/aspire-query adapter, domain/query.ts, ports/telemetry-query-port.ts, query.ts subpath entry, deno.json wiring, README update, layering guard test update, and adapter tests. Zero dashboard/panel/UI/rendering code. "dashboard" appears only in JSDoc referencing Aspire HTTP API endpoints the adapter wraps.

✅ Check 2 — Contract soundness

Pass. application/query is a typed Standard-Schema query contract (TraceQueryFilter validates limit/fields/resource). adapters/aspire-query implements the TelemetryQueryPort by calling Aspire Dashboard HTTP API (/api/telemetry/traces, /logs, /resources, /metrics) via fetch — wraps upstream APIs, no local re-implementation of OTLP querying.

✅ Check 3 — ./query subpath surface

Pass. "./query": "./query.ts" declared in deno.json exports + check task. deno doc --lint exits 0 across ALL 11 exports (including ./query.ts). deno publish --dry-run (no --allow-slow-types) exits 0.

✅ Check 4 — Gates + hygiene

Pass. deno check (91 ts/tsx) exit 0 · deno lint (91 ts/tsx) exit 0 · deno fmt --check (91 ts/tsx) exit 0 · deno test --filter telemetry 45 passed/0 failed · git diff c8f68721..5c965573 -- deno.lock EMPTY · zero new as casts (only JSDoc prose "as") · layering test updated with adapters/aspire-query import guard.

✅ Check 5 — Adapter test round-trip (bonus)

Pass. aspire_query_test.ts exercises full round-trip: fake fetch → Aspire JSON → domain types. Validates traces, logs, resources, metrics, span events/links. Graceful empty-array degradation on connection refused.

Drift

• README.md markdown table alignment flagged by deno fmt --check on Markdown only — NOT a source-quality gate failure (scoped ts/tsx fmt exits 0). Cosmetic, no action needed.

OPENHANDS_VERDICT: PASS

[rickylabs]

[PHASE: IMPL] [VERDICT: MERGE_CONFLICT_RESOLVED]

Resolved PR #567 after main advanced with T5 / PR #566.

Conflicts

• Conflict markers were limited to shared harness artifacts:
  • .llm/runs/beta6-nondash--supervisor/context-pack.md
  • .llm/runs/beta6-nondash--supervisor/drift.md
  • .llm/runs/beta6-nondash--supervisor/worklog.md
• Telemetry source files merged without conflict.
• A remote-only IMPL-EVAL artifact commit (2556b5f7) was preserved with a normal merge before pushing.

Resolution

• Additive merge: kept T5's span-link/fan-in exports and run evidence from main.
• Kept T7's telemetry query contract, @netscript/telemetry/query subpath, Aspire query adapter, and test evidence.
• Confirmed the merged root telemetry surface still exports both SpanLinkPort / createFanInLinks and the T7 query subpath.
• No tests were skipped or disabled.
• deno.lock validation churn was inspected and reverted; no lockfile change was pushed.
• No new as casts were added by the merge-resolution edit.

Commit

• 8f17117f998899e72fdb68bb51338536a1180c70

Gates

• deno run --allow-read --allow-run .llm/tools/run-deno-check.ts --root packages/telemetry --ext ts,tsx - exit 0; wrapper ran deno check --quiet --unstable-kv <files>; filesSelected=93, failedBatches=0, totalOccurrences=0.
• deno run --allow-read --allow-run .llm/tools/run-deno-lint.ts --root packages/telemetry --ext ts,tsx - exit 0; filesSelected=93, totalOccurrences=0.
• deno run --allow-read --allow-run .llm/tools/run-deno-fmt.ts --root packages/telemetry --ext ts,tsx - exit 0; filesSelected=93, failedBatches=0, findings=0.
• deno test --allow-env --allow-read packages/telemetry/tests/query/aspire_query_test.ts packages/telemetry/tests/layering_test.ts - exit 0; 8 passed / 0 failed.
• git diff --cached --check before commit - exit 0 after removing trailing Markdown whitespace in the merged T5 evaluator artifact.

PR state

• Pushed with explicit refspec: git push origin HEAD:refs/heads/feat/408-telemetry-t7-query.
• gh pr view 567 --json mergeable,mergeStateStatus after push: {"mergeable":"MERGEABLE","mergeStateStatus":"BLOCKED"}.