[IanMayo]

Summary

Makes the spec-240–deferred promise true: modelled debrief:* STAC fields now flow automatically to the writers' typed surface (read and write). LinkML's gen-typescript strips the debrief: prefix, so a naive StacItem.properties: StacExtensionProperties intersection matched none of the writers' real, prefixed access sites — they went through an untyped Record bag with as casts.

• One schema-driven generator step (shared/schemas/scripts/generate.py, pure fn prefix_extension_slots) rewrites modelled slot keys to their LinkML slot_uri verbatim across three classes: StacExtensionProperties (5), StacSummaries (3), StacAsset (2 new).
• Write-path typing — both hosts' mutation-path props re-typed from Record<string, unknown> to StacItemProperties, so write-side typos fail the build (the half a naive fix misses; ADR-033 / Article IV.5).
• Models debrief:toolId + debrief:snapshotTimestamp as additive StacAsset slots; removes the hand-cast asset as StacAsset & { 'debrief:toolId'?: string }.
• Closes the Implement tool parameter context menus (Feature 091) #240 Article II.1 audit deferral. On-disk JSON byte-for-byte unchanged; no new dependency; reuses the existing src/generated drift gate.

Changes

Schema + generator (foundational)

• stac.yaml: two additive optional StacAsset slots (tool_id→debrief:toolId, snapshot_timestamp→debrief:snapshotTimestamp).
• generate.py: prefix_extension_slots() + _load_extension_slot_uri_map(); one wired step over the three classes with RuntimeError self-guards. Regenerated TS + Pydantic (additive); deterministic.

Writer hosts

• apps/vscode/src/services/stacService.ts: drop read-site casts; re-type write-path props (removes the Record widening + ADR-011 eslint-disable); remove the StacAsset debrief:toolId hand-cast.
• apps/web-shell/src/services/stacWriterIdb.ts: re-type write-path props; drop the props as StacItem['properties'] cast.
• Typing debrief:provenance_log surfaced a latent Implement tool parameter context menus (Feature 091) #240 divergence (generated wide vs component narrowed-hybrid PropertiesProvenanceEntry) that the as-cast had masked — resolved with an explicit typed persistence→domain narrowing bridge on the read.

Decision: debrief:label excluded

Investigation showed it's a GeoJSON feature property / MCP annotation, not a STAC item/asset key; modelling it would re-create the mismatch this feature removes. Left for a future BaseFeatureProperties change.

Evidence

Test Results

Metric	Value
Python	2169 passed / 2 skipped / 1 xfailed
Generator transform (new)	7 passed
Type-level TS (read/write/asset)	6 passed
Writer unit suites (unchanged)	111 vscode + 54 web-shell passed
Lint / pyright / tsc (schemas + both apps)	clean

Verified: FR-002 (new slot flows with no generator edit — pure-fn unit test); FR-004/FR-012 (read and write typos fail the build); FR-008/SC-004 (byte-stable round-trip incl. new asset keys); SC-007 (asset hand-cast removed); deterministic regen + drift-clean.

Generated diff (before → after)

  export interface StacExtensionProperties {
-     platforms?: PlatformRecord[],            +     'debrief:platforms'?: PlatformRecord[],
-     ...                                      +     'debrief:...'
  }
  export interface StacSummaries {
-     debrief_platforms?: PlatformRecord[],    +     'debrief:platforms'?: PlatformRecord[],
  }
  export interface StacAsset {
      href: string,            // untouched (no extension slot_uri)
+     'debrief:toolId'?: string,
+     'debrief:snapshotTimestamp'?: string,
  }

Full artefacts: specs/256-prefix-aware-stac-typing/evidence/ (test-summary.md, round-trip-evidence.md, generated-diff.md, usage-example.md).

Test Plan

• uv run pytest (incl. new test_stac_prefix_transform.py, test_stac_roundtrip.py)
• pnpm --filter @debrief/schemas typecheck && test + tsc --noEmit on both apps
• writer unit suites unchanged (behaviour-preserving)
• ruff check + ruff format --check + pyright + eslint clean
• generator deterministic; src/generated drift-clean

Related

• Spec: specs/256-prefix-aware-stac-typing/spec.md
• Tasks: specs/256-prefix-aware-stac-typing/tasks.md
• ADR-040 (docs/project_notes/decisions.md); closes the Implement tool parameter context menus (Feature 091) #240 Article II.1 deferral

---

📖 Review in Spec Navigator: https://debrief.github.io/debrief-future/spec-navigator/?pr=663

Generated by Claude Code

[github-actions]

📋 Spec Navigator

Review this PR's specs interactively:
👉 Open in Spec Navigator
Raw spec directories changed in this PR:

• specs/256-prefix-aware-stac-typing/
  _{Updated for 89a4551 — the navigator reads spec content live from GitHub, so no rebuild is needed.}

[github-actions]

📋 Backlog Navigator

Review this PR's BACKLOG.md edits interactively:

👉 Open in Backlog Navigator

_{Updated for 89a4551 — the navigator reads BACKLOG.md live from this PR's head branch, so no rebuild is needed.}

[github-actions]

🚀 Preview Deployments

Code Server (Full VS Code Extension)

🖥️ Open Code Server

Browser-based VS Code with the Debrief extension and sample data pre-installed.

Web Shell (Standalone App)

📱 Open Web Shell

Use this for Playwright testing and demos - runs outside Storybook.

Storybook (Component Library)

📚 Open Storybook

Browse all components, stories, and documentation.

Briefing Renderer (Air-gapped Storyboard Player — spec #264)

🎬 Open Briefing Renderer

Standalone SPA that plays a Storyboard from a file://-origin zip. Loaded here on HTTPS as a static demo with the dev-fixture Storyboard (Channel Crossing — Demo Briefing).

---

All Links

Environment	Code Server	Web Shell	Storybook	Briefing Renderer
This PR	Open IDE	Open App	Open Storybook	Open Briefing
Main branch	—	Open App	Open Storybook	Open Briefing

Updated on commit dc07362

[github-actions]

Schema Docs Preview

Interactive site (clickable Mermaid, search, navigation)

Open HTML preview

Markdown sources (textual review on GitHub)

Browse Markdown on gh-pages

---

All Links

Surface	This PR	Main branch
HTML	Preview	Persistent
Markdown	Preview	On gh-pages

Updated on commit dc07362