@sprig-and-prose/sprig-scenes 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @sprig-and-prose/sprig-scenes
+
+## 0.1.1
+
+### Patch Changes
+
+- 9557987: Add dataset expectations, sprig-edge initial commit, and scene tutorial scaffolder

package/biome.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "always"
+    }
+  }
+}

package/docs/projection-expectations.md

@@ -0,0 +1,188 @@
+# Projection Expectations
+
+A metadata layer for declaring and tracking where actors are expected to be projected to external systems.
+
+## Overview
+
+Projection Expectations provide a **TDD-style approach for system boundaries**. During planning, you declare where actors should be projected (e.g., to Postgres tables, Snowflake warehouses, or OpenAPI schemas). Later, attestations verify whether those projections actually exist.
+
+This is metadata-only. No live database connections or verification logic is implemented in v0.
+
+## Syntax
+
+### 1. Declare Locations (Top-Level)
+
+```sprig
+locations {
+  TeamPostgres {
+    kind { 'postgres' }
+  }
+
+  Analytics {
+    kind { 'snowflake' }
+  }
+
+  PublicAPI {
+    kind { 'openapi' }
+  }
+}
+```
+
+**Location kinds are arbitrary strings:**
+- Use any string literal that describes your datastore
+- Examples: `'postgres'`, `'snowflake'`, `'openapi'`, `'fhir.r4'`, `'legacy-mainframe'`
+- No hardcoded validation - sprig is in the truth business, not the integration catalog business
+
+### 2. Declare Expectations (Actor-Level)
+
+```sprig
+actor PlayerSkill {
+  kind {
+    player { Player }
+    skill { Skill }
+    experience { integer }
+  }
+
+  identity { player skill }
+
+  expects {
+    project {
+      to { TeamPostgres }
+      as { table { player_skills } }
+    }
+
+    project {
+      to { PublicAPI }
+      as { schema { PlayerSkill } }
+    }
+  }
+}
+```
+
+**Supported artifact types:**
+- `table { name }` - Database table
+- `schema { name }` - API schema
+
+## Attestations
+
+Attestations are stored in `.sprig/SCENENAME.attestations.json`:
+
+```json
+{
+  "version": 1,
+  "actors": {
+    "PlayerSkill": [
+      {
+        "location": "TeamPostgres",
+        "artifactType": "table",
+        "name": "player_skills",
+        "status": "present",
+        "observedAt": "2026-02-13T10:00:00Z",
+        "shapeHash": "sha256:abc123"
+      }
+    ]
+  }
+}
+```
+
+## Status Computation
+
+Use `computeProjectionStatus()` to compare expectations with attestations:
+
+```javascript
+import { compileSceneFromText } from '@sprig-and-prose/sprig-scenes';
+import { loadAttestations, computeProjectionStatus } from '@sprig-and-prose/sprig-scenes';
+
+const manifest = compileSceneFromText(sceneSource);
+const attestations = await loadAttestations('.sprig/MyScene.attestations.json');
+
+const status = computeProjectionStatus(manifest, attestations);
+
+// Result:
+// {
+//   actors: {
+//     PlayerSkill: [
+//       {
+//         location: "TeamPostgres",
+//         artifactType: "table",
+//         name: "player_skills",
+//         status: "attested",      // or "expected" or "failed"
+//         expectation: { ... },
+//         attestation: { ... }     // present if attested/failed
+//       }
+//     ]
+//   }
+// }
+```
+
+### Status Values
+
+- **`expected`** (grey) - Projection declared but not yet attested
+- **`attested`** (green) - Attestation exists with status "present"
+- **`failed`** (red) - Attestation exists but status is not "present"
+- **`drifted`** (orange) - Reserved for future shape comparison (not implemented)
+
+## API
+
+### Compilation
+
+```javascript
+import { compileSceneFromText } from '@sprig-and-prose/sprig-scenes/compiler';
+
+const manifest = compileSceneFromText(sourceCode);
+// manifest.locations → { LocationName: { kind: string } }
+// manifest.actors.ActorName.expectations → ProjectionExpectation[]
+```
+
+### Attestations
+
+```javascript
+import { loadAttestations, saveAttestations } from '@sprig-and-prose/sprig-scenes/attestations';
+
+// Load (returns empty structure if file doesn't exist)
+const attestations = await loadAttestations('path/to/file.json');
+
+// Save
+await saveAttestations('path/to/file.json', attestations);
+```
+
+### Status Computation
+
+```javascript
+import { computeProjectionStatus } from '@sprig-and-prose/sprig-scenes/attestations/compute-status';
+
+const status = computeProjectionStatus(manifest, attestations);
+```
+
+## Validation
+
+The compiler validates:
+- Location names are unique
+- Location kinds are string literals (any string is valid)
+- Artifact types are valid (`table`, `schema`)
+- Expectation locations reference declared locations
+
+Invalid expectations throw errors during compilation.
+
+## Example
+
+See `examples/expectations-demo.js` for a complete working example.
+
+## Future Work (Not Implemented in v0)
+
+- Live database verification
+- Shape diffing and migration detection (status: "drifted")
+- Automated attestation generation
+- Additional artifact types (views, indices, etc.)
+
+Note: Location kinds are intentionally unrestricted - sprig stays in the truth business, not the integration catalog business.
+
+## Philosophy
+
+**Expectations are declarations, not implementations.**
+
+They specify *what should exist* without prescribing *how to create it*. This separation allows:
+- Early planning without infrastructure
+- UI visualization of projection status
+- Future integration with verification tools
+- Clear boundaries between truth layer and projection layer

package/example/players.example.js

@@ -0,0 +1,21 @@
+/**
+ * Tutorial-style example: compile scene, set portal, call derived.
+ * Run from repo root: node --import tsx packages/scenes/example/players.example.js
+ * Or from packages/scenes: node --import tsx example/players.example.js
+ */
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Scenes from '../src/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const scenePath = join(__dirname, '..', 'test', 'fixtures', 'players.scene.prose');
+
+const scene = await Scenes.compileFromPath(scenePath);
+
+scene.Players.set([
+  { id: 1, name: 'John' },
+  { id: 2, name: 'Jane' },
+]);
+
+console.log(scene.PlayerCount()); // 2
+console.log(scene.PlayerNames()); // 'Jane, John' (sorted ascending)

package/examples/expectations-demo.js

@@ -0,0 +1,146 @@
+/**
+ * @fileoverview Demo: How to use projection expectations
+ */
+
+import { compileSceneFromText } from '../src/compiler/compile_scene.js';
+import { computeProjectionStatus } from '../src/attestations/compute_status.js';
+
+// Example scene with locations and expectations
+const sceneSource = `
+scene DemoScene {
+  locations {
+    ProductionDB {
+      kind { 'postgres' }
+    }
+
+    Analytics {
+      kind { 'snowflake' }
+    }
+
+    PublicAPI {
+      kind { 'openapi' }
+    }
+  }
+
+  actors {
+    Player {
+      kind {
+        id { integer }
+        name { string }
+        email { string }
+      }
+
+      identity { id }
+
+      expects {
+        project {
+          to { ProductionDB }
+          as { table { players } }
+        }
+
+        project {
+          to { Analytics }
+          as { table { dim_players } }
+        }
+
+        project {
+          to { PublicAPI }
+          as { schema { Player } }
+        }
+      }
+    }
+
+    Game {
+      kind {
+        id { integer }
+        title { string }
+      }
+
+      identity { id }
+
+      expects {
+        project {
+          to { ProductionDB }
+          as { table { games } }
+        }
+      }
+    }
+  }
+
+  portals {
+    Players {
+      kind { [ Player ] }
+    }
+  }
+}
+`;
+
+// Compile the scene
+console.log('📝 Compiling scene...\n');
+const manifest = compileSceneFromText(sceneSource);
+
+console.log('✅ Scene compiled successfully!');
+console.log(`   Scene name: ${manifest.sceneName}`);
+console.log(`   Locations: ${Object.keys(manifest.locations).join(', ')}`);
+console.log(`   Actors: ${Object.keys(manifest.actors).join(', ')}\n`);
+
+// Show expectations
+console.log('🎯 Projection Expectations:\n');
+for (const [actorName, actorDef] of Object.entries(manifest.actors)) {
+  if (actorDef.expectations) {
+    console.log(`   ${actorName}:`);
+    for (const exp of actorDef.expectations) {
+      console.log(`     → ${exp.location} / ${exp.artifactType} / ${exp.name}`);
+    }
+  }
+}
+
+// Simulate attestations (some present, some missing)
+const attestations = {
+  version: 1,
+  actors: {
+    Player: [
+      {
+        location: 'ProductionDB',
+        artifactType: 'table',
+        name: 'players',
+        status: 'present',
+        observedAt: '2026-02-13T12:00:00Z',
+        shapeHash: 'sha256:abc123',
+      },
+      {
+        location: 'PublicAPI',
+        artifactType: 'schema',
+        name: 'Player',
+        status: 'present',
+        observedAt: '2026-02-13T12:00:00Z',
+        shapeHash: 'sha256:def456',
+      },
+    ],
+    // Note: Analytics dim_players is missing (expected but not verified)
+    // Note: Game is completely missing (all expected but not verified)
+  },
+};
+
+// Compute status
+console.log('\n📊 Computing projection status...\n');
+const status = computeProjectionStatus(manifest, attestations);
+
+// Display results
+console.log('Status Summary:\n');
+for (const [actorName, statuses] of Object.entries(status.actors)) {
+  console.log(`   ${actorName}:`);
+  for (const s of statuses) {
+    const icon =
+      s.status === 'attested' ? '🟢' : s.status === 'expected' ? '⚪' : '🔴';
+    console.log(
+      `     ${icon} ${s.status.toUpperCase().padEnd(10)} → ${s.location} / ${s.artifactType} / ${s.name}`,
+    );
+  }
+}
+
+console.log('\n✨ Legend:');
+console.log('     ⚪ EXPECTED  - Projection declared but not yet attested');
+console.log('     🟢 ATTESTED  - Projection exists and is attested');
+console.log('     🟠 DRIFTED   - Shape has changed (not yet implemented)');
+console.log('     🔴 FAILED    - Attestation exists but status is not "present"');

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@sprig-and-prose/sprig-scenes",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Scene compiler and canonical outputs for sprig",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./compiler": "./src/compiler/compile_scene_file.js",
+    "./compiler/compile_scene": "./src/compiler/compile_scene.js",
+    "./manifest": "./src/manifest/scene_manifest.js",
+    "./attestations": "./src/attestations/attestations.js",
+    "./attestations/compute-status": "./src/attestations/compute_status.js",
+    "./canonical/layout": "./src/canonical/layout.scene.json",
+    "./canonical/tools": "./src/canonical/tools.scene.json"
+  },
+  "scripts": {
+    "format": "biome format . --write",
+    "lint": "biome lint .",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --import tsx --test",
+    "build:canonical": "node scripts/build-canonical.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@sprig-and-prose/prose-parser": "*",
+    "@sprig-and-prose/sprig-scene-engine": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/scripts/build-canonical.js

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Build canonical scene manifest JSON
+ */
+
+import { readdir, writeFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { compileSceneFile } from '../src/compiler/compile_scene_file.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const canonicalDir = join(__dirname, '..', 'src', 'canonical');
+
+const entries = await readdir(canonicalDir);
+const canonicalFiles = entries
+  .filter((entry) => entry.endsWith('.scene.prose'))
+  .sort();
+
+for (const entry of canonicalFiles) {
+  const canonicalSource = join(canonicalDir, entry);
+  const outputFile = join(
+    canonicalDir,
+    entry.replace(/\.scene\.prose$/u, '.scene.json'),
+  );
+  const manifest = await compileSceneFile(canonicalSource);
+  const json = `${JSON.stringify(manifest, null, 2)}\n`;
+  await writeFile(outputFile, json, 'utf-8');
+}

package/src/api/PortalHandle.js

@@ -0,0 +1,22 @@
+/**
+ * Portal handle: set/get/clear for one portal, synced to runtime.
+ * @param {string} name - Portal name
+ * @param {Record<string, unknown>} portalValues - Mirror of portal data (for get())
+ * @param {{ setPortalData(name: string, value: unknown): void }} runtime - Engine runtime
+ * @returns {{ set(value: unknown): void; get(): unknown; clear(): void }}
+ */
+export function createPortalHandle(name, portalValues, runtime) {
+  return {
+    set(value) {
+      portalValues[name] = value;
+      runtime.setPortalData(name, value);
+    },
+    get() {
+      return portalValues[name];
+    },
+    clear() {
+      delete portalValues[name];
+      runtime.setPortalData(name, undefined);
+    },
+  };
+}

package/src/api/SceneCompiler.js

@@ -0,0 +1,24 @@
+/**
+ * Wraps the scene compiler: compileFromPath (async) and compileFromString (sync).
+ */
+
+import { compileSceneFile } from '../compiler/compile_scene_file.js';
+import { compileSceneFromText } from '../compiler/compile_scene.js';
+
+/**
+ * Compile a scene from a file path.
+ * @param {string} path
+ * @returns {Promise<import('../manifest/scene_manifest.js').SceneManifest>}
+ */
+export async function compileFromPath(path) {
+  return compileSceneFile(path);
+}
+
+/**
+ * Compile a scene from source text.
+ * @param {string} source
+ * @returns {import('../manifest/scene_manifest.js').SceneManifest}
+ */
+export function compileFromString(source) {
+  return compileSceneFromText(source);
+}

package/src/api/SceneInstance.js

@@ -0,0 +1,50 @@
+/**
+ * SceneInstance: Proxy that returns PortalHandle for portal names, callable for derived names,
+ * and throws formatUnknownMemberError for unknown names.
+ */
+
+import { createPortalHandle } from './PortalHandle.js';
+import { formatUnknownMemberError } from './formatUnknownMemberError.js';
+
+/**
+ * Create a SceneInstance (Proxy) for the given manifest and runtime.
+ * @param {import('../manifest/scene_manifest.js').SceneManifest} manifest
+ * @param {{ setPortalData(name: string, value: unknown): void; getDerived(blockName: string): unknown }} runtime
+ * @returns {Proxy}
+ */
+export function createSceneInstance(manifest, runtime) {
+  const portalValues = /** @type {Record<string, unknown>} */ ({});
+
+  const portalHandles = /** @type {Record<string, { set(value: unknown): void; get(): unknown; clear(): void }} */ ({});
+  function getPortalHandle(name) {
+    if (!portalHandles[name]) {
+      portalHandles[name] = createPortalHandle(name, portalValues, runtime);
+    }
+    return portalHandles[name];
+  }
+
+  const target = {};
+  return new Proxy(target, {
+    get(_obj, prop) {
+      const name = typeof prop === 'string' ? prop : String(prop);
+      // Allow then/catch/finally so the Proxy is not treated as thenable (e.g. by test runners).
+      if (name === 'then' || name === 'catch' || name === 'finally') {
+        return undefined;
+      }
+      if (Object.prototype.hasOwnProperty.call(manifest.portals, name)) {
+        return getPortalHandle(name);
+      }
+      if (Object.prototype.hasOwnProperty.call(manifest.derived, name)) {
+        return () => runtime.getDerived(name);
+      }
+      throw formatUnknownMemberError(name, manifest);
+    },
+    has(_obj, prop) {
+      const name = typeof prop === 'string' ? prop : String(prop);
+      return (
+        Object.prototype.hasOwnProperty.call(manifest.portals, name) ||
+        Object.prototype.hasOwnProperty.call(manifest.derived, name)
+      );
+    },
+  });
+}

package/src/api/SceneRuntime.js

@@ -0,0 +1,14 @@
+/**
+ * Wraps the scene-engine runtime: given manifest, returns engine's createSceneRuntime(manifest).
+ */
+
+import { createSceneRuntime } from '@sprig-and-prose/sprig-scene-engine';
+
+/**
+ * Create a runtime for the given manifest.
+ * @param {import('../manifest/scene_manifest.js').SceneManifest} manifest
+ * @returns {import('@sprig-and-prose/sprig-scene-engine').SceneRuntime}
+ */
+export function createRuntime(manifest) {
+  return createSceneRuntime(manifest);
+}

package/src/api/formatUnknownMemberError.js

@@ -0,0 +1,18 @@
+/**
+ * Build a helpful error for unknown scene member access.
+ * @param {string} memberName
+ * @param {{ portals: Record<string, unknown>; derived: Record<string, unknown> }} manifest
+ * @returns {Error}
+ */
+export function formatUnknownMemberError(memberName, manifest) {
+  const portalNames = Object.keys(manifest.portals ?? {}).sort();
+  const derivedNames = Object.keys(manifest.derived ?? {}).sort();
+  const portalList = portalNames.length ? portalNames.join(', ') : '(none)';
+  const derivedList = derivedNames.length ? derivedNames.join(', ') : '(none)';
+  const message = [
+    `Unknown scene member "${memberName}".`,
+    `Known portals: ${portalList}.`,
+    `Known derived values: ${derivedList}.`,
+  ].join('\n');
+  return new Error(message);
+}

package/src/attestations/attestations.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Attestation file management for projection expectations
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+
+/**
+ * Single attestation for an actor projection.
+ * @typedef {Object} Attestation
+ * @property {string} location - Location name
+ * @property {'table' | 'schema'} artifactType - Type of artifact
+ * @property {string} name - Artifact name
+ * @property {'present' | 'absent'} status - Attestation status
+ * @property {string} observedAt - ISO 8601 timestamp
+ * @property {string} [shapeHash] - Optional shape hash for verification
+ */
+
+/**
+ * Attestation file structure.
+ * @typedef {Object} AttestationFile
+ * @property {1} version - File format version
+ * @property {Record<string, Attestation[]>} actors - Attestations by actor name
+ */
+
+/**
+ * Load attestations from a JSON file.
+ * @param {string} filePath - Path to attestation file
+ * @returns {Promise<AttestationFile>}
+ */
+export async function loadAttestations(filePath) {
+  try {
+    const text = await readFile(filePath, 'utf-8');
+    const data = JSON.parse(text);
+    
+    if (!data.version || data.version !== 1) {
+      throw new Error(`Invalid attestation file version. Expected 1, got ${data.version}`);
+    }
+    
+    if (!data.actors || typeof data.actors !== 'object') {
+      throw new Error('Attestation file must have an actors object');
+    }
+    
+    return data;
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      // File doesn't exist, return empty attestations
+      return {
+        version: 1,
+        actors: {},
+      };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Save attestations to a JSON file.
+ * @param {string} filePath - Path to attestation file
+ * @param {AttestationFile} data - Attestation data to save
+ * @returns {Promise<void>}
+ */
+export async function saveAttestations(filePath, data) {
+  const json = JSON.stringify(data, null, 2);
+  await writeFile(filePath, json, 'utf-8');
+}