Skip to content

Artifact must be consumable downstream without per-version reconciliation (lock layout + emit content hash + always emit engine.js) #24

@ebootheee

Description

@ebootheee

Context: a downstream consumer (the "Mippy" equity platform) loads these chunked artifacts to run locks/distributions. Examining the 2026-05-28 outpost-a1-v2 / outpost-a2-v2 regen against the consumer's loader, the generator output and the consumer contract have diverged on five axes — each of which forces a manual fix on every regeneration. We need the artifact to be directly consumable across versions. Please treat the following as the contract.

1. chunked/engine.js (the run orchestrator) is load-bearing — always emit it, or fail loud

v2 shipped with no engine.js (lost to the dependency-graph OOM — see #23). The consumer's load() does import(chunked/engine.js) and requires export function run(). A build that emits sheets + maps but not the orchestrator is an inert artifact. Please make the build fail loudly rather than emit a partial artifact — a silent partial is worse than a hard error.

2. Stable, documented layout (don't let paths drift between versions)

Lock these paths: chunked/engine.js, chunked/sheets/*.mjs, chunked/{named-outputs,named-inputs,cell-types}.json, chunked/_ground-truth.json. The consumer keys off them; drift = breakage.

3. Emit a content hash of the artifact, with a specified algorithm

The consumer refuses to serve an artifact whose hash doesn't match its manifest (tamper guard). It computes: sha256 over chunked/engine.js bytes, then for each file in chunked/sheets/ sorted by filename: hash the filename then the file bytes. Please emit this hash (e.g. engineArtifactHash in a sidecar) computed the same way, so the consumer can verify rather than trust. (Happy to share the exact 20-line function.)

4. Declare version + model identity in a stable field, not the directory name

v2 baked the version into the dir (outpost-a1-v2). The consumer parses {platform}-{class} from the dir and reads the version from the manifest. Please put versionTag (+ platform/class identity) in the manifest, and keep the dir name version-free.

5. Manifest: one location, one schema, held across versions

v2 put manifest.json in chunked/ with a {model,timeline,outputs} schema. That's fine as the contract map — but please keep its location + top-level shape stable across regenerations so consumers don't chase it.

This is the "survive across versions" ask: today every regen needs hand-reconciliation, which is unsustainable code debt. Locking 1–5 makes regeneration mechanical. Related: #23 (the OOM that caused #1).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions