[EiffL]

Summary

• replace MySTRA's custom YAML loader, resolved store, provenance reconstruction, and output aliasing with @astra-spec/sdk project resolution and canonical indexes
• keep MyST roles and directives synchronous by emitting lightweight requests, then resolve the project once in a single asynchronous document transform
• publish the SDK's exact ResolvedAnalysisBundle through a versioned, data-only carrier, with separately rewritten static artifact resources and SDK-collected citations
• publish deterministic identity and display context on AST nodes so a theme can render rich previews without parsing labels, reconstructing provenance, or guessing routes
• update authoring and theming documentation around canonical SDK paths, multi-page analysis navigation, live values, resolved universe state, and pending/inactive records

Publication contract

Every transformed page carries:

{
  schemaVersion: 'astra-publication-bundle.v1',
  activeAnalysisPath: string,
  bundle: ResolvedAnalysisBundle,
}

The bundle is passed through unchanged. MyST-rewritten artifact URLs remain separate and are rejoined by canonical outputPath plus the SDK cacheToken, so the theme does not need a parallel data model. Visible artifacts and hidden static-resource links are emitted relative to the current source page, including nested MyST pages, while SDK binding paths remain untouched.

The small SDK host cache records every file read, directory listing, and stat result used during project resolution. It deduplicates concurrent page builds while invalidating on source, universe, or artifact changes—including newly materialized outputs.

ASTRA component prose is inserted after MyST's document-level transformations, so MySTRA applies MyST's official math nesting, labeling, and KaTeX rendering passes at that boundary. Inline and display math therefore reach themes fully rendered, while malformed equations report through the page's normal VFile diagnostics.

Theme metadata boundary

Placed record carriers and inline record references expose only resolvable SDK identity:

{ kind, id, canonicalPath }

Analysis references use a deliberately separate address:

{ kind: 'analysis', id, analysisPath, href? }

href exists only when a concrete, unambiguous project.toc page maps to that analysis using MyST's route rules. No /<analysis-id> URL is invented. Active-page scope and route mapping share the same source-stem logic for Markdown, notebooks, TeX, and .myst.json pages.

Inline values additionally carry the relevant type, selection, unit, product, col, and filter strings when available. Optional values are omitted rather than serialized as empty or undefined compatibility fields.

Breaking alpha cleanup

This is a deliberate clean cutover with no legacy compatibility layer:

• removes the author-facing astra:numref and custom astra:ref surfaces; explicit directive labels use standard MyST {ref}
• removes the prior-insights and filter= aliases, author-addressable universe paths, and /static artifact fallback
• removes guessed sub-analysis URLs and all legacy resolved-store/provenance code
• emits only canonical SDK record paths on inline metadata; unresolved references fall back to neutral text without fabricated metadata

Verification

• npm run typecheck
• npm run build
• npm run bundle, followed by a successful import of the standalone bundle
• npm test — 72 tests
• npm run docs:build — strict build, no issues
• live DESI build — all 28 late output-caption equations render as KaTeX with no raw-TeX warning fallback
• git diff --check

Companion consumer work:

• LightconeResearch/astra-ui#9 adds the shared accessible hover/focus record-preview API.
• LightconeResearch/astra-theme#10 consumes this carrier while preserving a narrow upstream MyST theme delta.

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[EiffL]

LGTM

[EiffL]

LGTM