Emit VISOR artifact bundle

docs/CHANGELOG.md

@@ -6,14 +6,19 @@ All packages (`@flyingrobots/bijou`, `@flyingrobots/bijou-node`, `@flyingrobots/
 
 ## [Unreleased]
 
+### Added
+
+- **VISOR artifact bundle proof** — `@flyingrobots/bijou` now exports
+  `createVisorArtifactBundleFromGraphql()`, `createVisorArtifactBundle()`, and
+  `visor-artifact-bundle/1` types for #458 / [`DX-049`](design/DX-049-visor-artifact-bundle-proof.md).
+  The builder wraps the checked-in DOGFOOD GraphQL fixture path,
+  `bijou-block/1`, `ui-scene-ir/1`, `graphql-bijou-block-debug/1`, replay
+  metadata, visual scene facts, raw and semantic source hashes, and stable
+  receipts while leaving #459 packed-cell validation and external
+  renderer/debugger work out of scope.
+
 ### Changed
 
-- **VISOR artifact bundle shaping** —
-  [`DX-049`](design/DX-049-visor-artifact-bundle-proof.md) scopes #458 around a
-  deterministic `visor-artifact-bundle/1` that wraps the existing GraphQL
-  fixture path, `bijou-block/1`, `ui-scene-ir/1`, replay metadata, visual scene
-  facts, and stable hashes while leaving #459 packed-cell validation and
-  external renderer/debugger work out of scope.
 - **Future release milestone triage** — The GitHub backlog is now assigned to
   explicit `v8.0.0`, `v8.1.0`, `v8.2.0`, `v9.0.0`, and `v10.0.0` horizons;
   `Beyond` and open unmilestoned issue queues are empty; and

docs/design/DX-049-visor-artifact-bundle-proof.md

@@ -164,9 +164,14 @@ visor-artifact-bundle/1
   receipts[]
 ```
 
-`bundleHash` is computed from the canonical bundle payload with the hash field
-itself omitted. Hashing must use the same deterministic JSON rules already used
-by the GraphQL block and scene IR proof path.
+`sourceHash` records the raw source text hash. `normalizedSourceHash` records
+the semantic source hash inherited from the compiled `bijou-block/1` artifact.
+`bundleHash` is computed from the canonical semantic bundle payload with raw
+`source.text`, raw `sourceHash` copies, and `bundleHash` itself omitted. That
+lets VISOR inspect exact source text and raw source identity while preserving a
+stable semantic bundle hash across whitespace-only SDL edits. Hashing must use
+the same deterministic JSON rules already used by the GraphQL block and scene
+IR proof path.
 
 ## Replay Metadata Contract
 
@@ -298,26 +303,27 @@ An agent should be able to answer, from the bundle alone:
 
 ## Validation Plan
 
-Current design PR validation:
+Current implementation validation:
 
 ```bash
-npx vitest run --config vitest.config.ts tests/cycles/WF-130/roadmap-goalpost-policy.part01.test.ts tests/cycles/WF-130/roadmap-goalpost-policy.part02.test.ts tests/cycles/WF-130/roadmap-goalpost-policy.part04.test.ts
+npx vitest run --config vitest.config.ts tests/cycles/DX-049
+npx vitest run --config vitest.config.ts \
+  tests/cycles/WF-130/roadmap-goalpost-policy.part01.test.ts \
+  tests/cycles/WF-130/roadmap-goalpost-policy.part02.test.ts \
+  tests/cycles/WF-130/roadmap-goalpost-policy.part04.test.ts
 npm run docs:inventory
 npm run typecheck:test
 npm run code-dojo:changed
 npm run lint
 git diff --check
 ```
 
-Future implementation validation after the RED-test slice creates
-`tests/cycles/DX-049`:
-
-```bash
-npx vitest run --config vitest.config.ts tests/cycles/DX-049
-```
-
 ## Closeout Notes
 
-Open. This design starts #458. Keep `needs-design` on the issue until the
-design PR lands; keep `work-in-progress` on the issue while the branch and PR
-carry the cycle.
+Implementation in progress. The design PR has landed, so #458 no longer needs
+`needs-design`. The implementation branch now carries focused
+`tests/cycles/DX-049` coverage for the public bundle builder, exported bundle
+type, raw-versus-semantic source hashes, replay metadata, visual scene facts,
+absolute source-name rejection, malformed source rejection, duplicate visual
+node rejection, and hash-mismatch rejection. Keep `work-in-progress` on the
+issue while the branch and PR carry the implementation cycle.

packages/bijou/src/core/visor-artifact-bundle.part01.ts

@@ -0,0 +1,141 @@
+import type {
+  UiNodeKind,
+  UiSceneIr,
+  UiSceneLowerMode,
+  UiSceneLoweringOptions,
+  UiTargetProfile,
+  UiTextRef,
+} from './ui-scene-ir.js';
+import type {
+  BijouBlockArtifact,
+  GraphqlBijouBlockDebugSummary,
+} from './graphql-bijou-block.part01.js';
+
+export const VISOR_ARTIFACT_BUNDLE_VERSION = 'visor-artifact-bundle/1' as const;
+export const VISOR_REPLAY_METADATA_VERSION = 'visor-replay-metadata/1' as const;
+export const VISOR_VISUAL_SCENE_FACTS_VERSION = 'visor-visual-scene-facts/1' as const;
+
+export type VisorArtifactBundleVersion = typeof VISOR_ARTIFACT_BUNDLE_VERSION;
+export type VisorReplayMetadataVersion = typeof VISOR_REPLAY_METADATA_VERSION;
+export type VisorVisualSceneFactsVersion = typeof VISOR_VISUAL_SCENE_FACTS_VERSION;
+
+export interface CreateVisorArtifactBundleFromGraphqlOptions extends UiSceneLoweringOptions {
+  readonly fixtureId: string;
+  readonly sourceName: string;
+  readonly scenarioId?: string;
+  readonly deterministicSeed?: string;
+}
+
+export interface CreateVisorArtifactBundleInput extends CreateVisorArtifactBundleFromGraphqlOptions {
+  readonly sourceText: string;
+  readonly bijouBlock: BijouBlockArtifact;
+  readonly uiScene: UiSceneIr;
+  readonly debugSummary: GraphqlBijouBlockDebugSummary;
+}
+
+export interface VisorArtifactBundleFixture {
+  readonly id: string;
+  readonly sourceName: string;
+  readonly sourceHash: string;
+  readonly normalizedSourceHash: string;
+}
+
+export interface VisorArtifactBundleSource {
+  readonly language: 'graphql';
+  readonly text: string;
+}
+
+export interface VisorArtifactBundleArtifacts {
+  readonly bijouBlock: BijouBlockArtifact;
+  readonly uiScene: UiSceneIr;
+  readonly debugSummary: GraphqlBijouBlockDebugSummary;
+}
+
+export interface VisorReplayStep {
+  readonly id: string;
+  readonly label: string;
+  readonly inputHashes: readonly string[];
+  readonly outputHashes: readonly string[];
+}
+
+export interface VisorReplayMetadata {
+  readonly replayVersion: VisorReplayMetadataVersion;
+  readonly scenarioId: string;
+  readonly fixtureId: string;
+  readonly deterministicSeed: string;
+  readonly consumedHashes: {
+    readonly sourceHash: string;
+    readonly normalizedSourceHash: string;
+    readonly artifactHash: string;
+    readonly sceneHash: string;
+    readonly debugSummaryHash: string;
+    readonly visualFactsHash: string;
+  };
+  readonly steps: readonly VisorReplayStep[];
+}
+
+export interface VisorVisualNodeFact {
+  readonly nodeId: string;
+  readonly kind: UiNodeKind;
+  readonly role?: string;
+  readonly component?: string;
+  readonly parentId?: string;
+  readonly childNodeIds: readonly string[];
+  readonly text?: UiTextRef;
+  readonly i18nKeys: readonly string[];
+  readonly tokenRefs: readonly string[];
+  readonly actionIds: readonly string[];
+  readonly bindingIds: readonly string[];
+  readonly sourceRefs: readonly string[];
+}
+
+export interface VisorVisualLowerModeFact {
+  readonly mode: UiSceneLowerMode;
+  readonly surfaceHash: string;
+  readonly rowsHash: string;
+}
+
+export interface VisorVisualSceneFacts {
+  readonly visualFactsVersion: VisorVisualSceneFactsVersion;
+  readonly sceneId: string;
+  readonly rootNodeId: string;
+  readonly targetProfiles: readonly UiTargetProfile[];
+  readonly nodeFacts: readonly VisorVisualNodeFact[];
+  readonly lowerModes: readonly VisorVisualLowerModeFact[];
+}
+
+export interface VisorArtifactBundleHashes {
+  readonly sourceHash: string;
+  readonly normalizedSourceHash: string;
+  readonly artifactHash: string;
+  readonly sceneHash: string;
+  readonly debugSummaryHash: string;
+  readonly replayHash: string;
+  readonly visualFactsHash: string;
+  readonly bundleHash: string;
+}
+
+export interface VisorArtifactBundleReceipt {
+  readonly subject: string;
+  readonly version: string;
+  readonly hash: string;
+}
+
+export interface VisorArtifactBundle {
+  readonly bundleVersion: VisorArtifactBundleVersion;
+  readonly fixture: VisorArtifactBundleFixture;
+  readonly source: VisorArtifactBundleSource;
+  readonly artifacts: VisorArtifactBundleArtifacts;
+  readonly replay: VisorReplayMetadata;
+  readonly visual: VisorVisualSceneFacts;
+  readonly hashes: VisorArtifactBundleHashes;
+  readonly receipts: readonly VisorArtifactBundleReceipt[];
+}
+
+export type VisorArtifactBundleHashBody = Omit<VisorArtifactBundleHashes, 'bundleHash'>;
+
+export type VisorArtifactBundleWithoutHash = Omit<VisorArtifactBundle, 'hashes'> & {
+  readonly hashes: VisorArtifactBundleHashBody & {
+    readonly bundleHash?: string;
+  };
+};

packages/bijou/src/core/visor-artifact-bundle.part02.ts

@@ -0,0 +1,111 @@
+import { hashUiSceneValue } from './ui-scene-ir.js';
+import { compileGraphqlBijouBlock } from './graphql-bijou-block.part02.js';
+import { lowerBijouBlockToUiScene } from './graphql-bijou-block.part03.js';
+import { createGraphqlBijouBlockDebugSummary } from './graphql-bijou-block.part04.js';
+import { normalizeSourceName } from './graphql-bijou-block.part10.js';
+import {
+  VISOR_ARTIFACT_BUNDLE_VERSION,
+  type CreateVisorArtifactBundleFromGraphqlOptions,
+  type CreateVisorArtifactBundleInput,
+  type VisorArtifactBundle,
+  type VisorArtifactBundleHashBody,
+} from './visor-artifact-bundle.part01.js';
+import {
+  createVisorReplayMetadata,
+  createVisorVisualSceneFacts,
+} from './visor-artifact-bundle.part03.js';
+import {
+  assertDebugSummaryMatchesFacts,
+  assertSceneMatchesArtifact,
+  createReceipts,
+  normalizeLogicalId,
+  semanticBundleHashPayload,
+} from './visor-artifact-bundle.part04.js';
+
+export function createVisorArtifactBundleFromGraphql(
+  source: string,
+  options: CreateVisorArtifactBundleFromGraphqlOptions,
+): VisorArtifactBundle {
+  const sourceName = normalizeSourceName(options.sourceName);
+  const bijouBlock = compileGraphqlBijouBlock(source, { sourceName });
+  const uiScene = lowerBijouBlockToUiScene(bijouBlock);
+  const debugSummary = createGraphqlBijouBlockDebugSummary(bijouBlock, options);
+  return createVisorArtifactBundle({
+    ...options,
+    sourceName,
+    sourceText: source,
+    bijouBlock,
+    uiScene,
+    debugSummary,
+  });
+}
+
+export function createVisorArtifactBundle(input: CreateVisorArtifactBundleInput): VisorArtifactBundle {
+  const fixtureId = normalizeLogicalId(input.fixtureId, 'fixtureId');
+  const scenarioId = normalizeLogicalId(input.scenarioId ?? `${fixtureId}:graphql-to-ui-scene`, 'scenarioId');
+  const deterministicSeed = input.deterministicSeed ?? 'no-randomness';
+  const sourceName = normalizeSourceName(input.sourceName);
+
+  if (input.bijouBlock.sourceName !== sourceName) {
+    throw new Error('visor-artifact-bundle/1 sourceName does not match bijou-block/1.');
+  }
+
+  const visual = createVisorVisualSceneFacts(input.uiScene, input.debugSummary);
+  const visualFactsHash = hashUiSceneValue(visual);
+  assertSceneMatchesArtifact(input.bijouBlock, input.uiScene);
+  assertDebugSummaryMatchesFacts(input.bijouBlock, input.uiScene, input.debugSummary);
+
+  const sourceHash = hashUiSceneValue(input.sourceText);
+  const normalizedSourceHash = input.bijouBlock.sourceHash;
+  const artifactHash = hashUiSceneValue(input.bijouBlock);
+  const sceneHash = hashUiSceneValue(input.uiScene);
+  const debugSummaryHash = input.debugSummary.summaryHash;
+  const replay = createVisorReplayMetadata({
+    fixtureId,
+    scenarioId,
+    deterministicSeed,
+    sourceHash,
+    normalizedSourceHash,
+    artifactHash,
+    sceneHash,
+    debugSummaryHash,
+    visualFactsHash,
+  });
+  const replayHash = hashUiSceneValue(replay);
+  const hashes: VisorArtifactBundleHashBody = {
+    sourceHash,
+    normalizedSourceHash,
+    artifactHash,
+    sceneHash,
+    debugSummaryHash,
+    replayHash,
+    visualFactsHash,
+  };
+  const bundleWithoutHash = {
+    bundleVersion: VISOR_ARTIFACT_BUNDLE_VERSION,
+    fixture: { id: fixtureId, sourceName, sourceHash, normalizedSourceHash },
+    source: { language: 'graphql' as const, text: input.sourceText },
+    artifacts: {
+      bijouBlock: input.bijouBlock,
+      uiScene: input.uiScene,
+      debugSummary: input.debugSummary,
+    },
+    replay,
+    visual,
+    hashes: { ...hashes, bundleHash: undefined },
+    receipts: createReceipts({
+      artifactHash,
+      sceneHash,
+      debugSummaryHash,
+      replayHash,
+      visualFactsHash,
+    }),
+  };
+  return {
+    ...bundleWithoutHash,
+    hashes: {
+      ...hashes,
+      bundleHash: hashUiSceneValue(semanticBundleHashPayload(bundleWithoutHash)),
+    },
+  };
+}