Skip to content

SPEC_CHECKLIST.md

Latest commit

 

History

History
181 lines (166 loc) · 7.94 KB

SPEC_CHECKLIST.md

File metadata and controls

181 lines (166 loc) · 7.94 KB

SPEC Checklist

Legend:

  • done
  • open

This checklist tracks the remaining work to fully satisfy SPEC.md for the kernel, DevTools, and raw mode before moving on to OTEL.

1. Planning / spec hygiene

  • SPEC.md updated to reflect the dataset-kernel direction
  • SPEC.md updated with presentation/runtime-first guidance (pretty, table, manual string building)
  • SPEC.md updated with a pre-OTEL hardening gate
  • SPEC_CHECKLIST.md created
  • README.md updated to match the new runtime/kernel architecture
  • agent-facing docs/examples updated to teach ds, pretty, table, and manual string building

2. Kernel foundation

  • source-driver interface exists
  • dataset session/kernel exists
  • stable ds query root exists
  • lazy layer host exists
  • generic Node HTTP server + custom router exists
  • bundled build outputs exist via esbuild
  • basic artifact/file/workspace subsystem exists
  • generic schema/tables/reports/artifacts/exports routes exist
  • layer status inspection exists
  • global/shared CAS exists
  • multi-dataset composition exists

3. Query runtime, table algebra, and presentation

  • ds.reports.run(name, args) exists
  • ds.tables.get(name).rows() exists
  • ds.tables.get(name).count() exists
  • ds.schema.paths() exists
  • ds.schema.samples(path) exists
  • ds.tables.get(name) returns a chainable query builder/handle
  • formal table query plan exists (select / where / orderBy / offset / limit)
  • filtered count uses the same query-plan surface
  • provider pushdown hook exists for direct table-plan execution
  • JS fallback plan execution is implemented for all tables
  • global pretty(value) exists in the query runtime
  • global table(value) exists in the query runtime
  • table query handles expose .pretty()
  • table query handles expose .table()
  • report handles/bound invocations expose .pretty()
  • CLI/runtime share the same presentation helpers instead of duplicating formatting logic
  • presentation output is documented and stable enough for agent workflows

4. Provenance, lifecycle, and safety

  • basic provenance exists in some derived DevTools outputs
  • normalized provenance contract exists across major rows/reports
  • facts/dims/views/reports consistently expose provenance or provenance refs
  • layer metadata includes dependency keys and size estimates where feasible
  • layer eviction exists
  • layer pin/unpin exists
  • export/materialization lease release exists
  • workspace cleanup policy exists (TTL and/or quotas)
  • operator-visible status explains retained vs evicted layers/exports
  • workspace/export lifecycle is considered production-real, not aspirational

5. DevTools core loading and dimensions

  • raw DevTools loading exists
  • raw event access exists
  • threads dimension exists
  • requests dimension exists
  • screenshots dimension exists
  • interactions dimension exists
  • scripts dimension exists
  • source maps dimension exists
  • original sources dimension exists
  • layout shifts dimension exists (basic)
  • soft navigations dimension exists (basic)
  • processes dimension exists
  • frames dimension exists
  • workers dimension exists
  • compositor/layer-related dimensions exist where supported by the trace
  • tasks dimension is explicit and complete rather than only task-like derived views

6. DevTools facts and indexes

  • event-centric raw/fact access exists at a basic level
  • explicit instant-event facts exist
  • explicit slice-event facts exist
  • explicit async/flow facts exist
  • CPU sample facts exist
  • object-lifecycle facts exist where useful
  • reusable indexes by name/category/phase/thread exist
  • reusable indexes by request ID/script ID/interaction ID/frame sequence/node ID/url exist

7. DevTools views and reports

  • render measures view exists
  • frame pipeline view exists (basic)
  • main-thread tasks view exists (basic)
  • code hotspots view exists
  • CPU hotspots view exists (basic aggregation)
  • interaction windows view exists
  • visual changes view exists
  • devtools.summary report exists
  • devtools.interaction report exists
  • devtools.frame report exists
  • devtools.request report exists
  • devtools.script report exists
  • devtools.soft-navigation report exists
  • devtools.hotspots report exists
  • render-measure aggregate-by-component views are complete
  • render-measure scoped views by interaction/window are complete
  • network waterfall view exists
  • frame pipeline stage timing extraction is richer than state-level summaries
  • interaction/task/frame/request cross-correlation is complete enough to avoid bespoke agent joins
  • major DevTools reports have first-class readable renderers

8. DevTools CPU profile depth

  • CPU hotspot aggregation exists
  • ProfileChunk streams are decoded into normalized CPU sample facts
  • CPU node/frame dimensions are canonicalized
  • self time vs total time semantics are implemented
  • folded-stack / call-tree derived views exist
  • CPU timeline buckets exist
  • interaction-scoped CPU hotspot views exist
  • task-scoped CPU hotspot views exist
  • CPU attribution through scripts/source maps/sources is robust

9. DevTools network/body/artifact depth

  • request lifecycle correlation exists
  • request timing/protocol/header metadata exists at a useful level
  • screenshots export collection exists
  • scripts export collection exists
  • source maps export collection exists
  • original sources export collection exists
  • network response/request bodies are exposed as artifacts when present
  • devtools.network-bodies collection exists
  • request ↔ body linkage is explicit
  • request ↔ interaction / visual-change correlation is stronger

10. DevTools layout/soft-navigation depth

  • layout shift rows exist
  • soft navigation rows exist
  • clustered layout-shift entities exist
  • impacted nodes/rects are normalized
  • soft-navigation task linkage exists
  • layout/soft-navigation relation to interactions/frames/screenshots is complete enough for first-class investigation

11. Raw mode

  • raw JSON driver exists
  • raw summary report exists
  • path cataloging exists
  • path samples exist
  • time-field detection exists
  • shallow inferred tables exist
  • embedded blob extraction exists (basic)
  • raw document export exists
  • embedded blob export collection exists
  • nested-array inferred tables exist
  • path-based inferred-table naming is stable and well-specified
  • richer type summaries/path stats exist
  • wrapper-object blob detection exists
  • byte-array blob detection exists
  • gzip/base64 text-or-JSON blob detection exists
  • media sniffing from magic bytes exists
  • blob confidence scoring exists
  • richer blob metadata and export manifests exist
  • raw summary/path catalogs have first-class readable renderers

12. Pre-OTEL hardening gate

  • query builder / pushdown-ready table plan is complete
  • presentation layer is complete enough for agent workflows
  • provenance normalization is complete enough to be relied upon broadly
  • layer/workspace lifecycle basics are complete enough to operate confidently
  • DevTools completion criteria are met
  • raw-mode completion criteria are met
  • README/examples/agent docs match the real runtime surface

13. Future after the DevTools/raw milestone

  • OTEL driver
  • relations/edges pack
  • global CAS / content-addressed blob store
  • multi-dataset composition
  • Sentry driver
  • bundle-analysis driver on the new architecture
    • vite-bundle-analyzer JSON driver exists
    • Next.js Turbopack bundle analyzer directory driver exists
    • bundle analysis tables / views / reports are documented in the trace-server skill