@treeseed/sdk 0.11.0 → 0.12.4

package/dist/scenes/diagram-providers.js

@@ -0,0 +1,181 @@
+import { sceneErrorDiagnostic, sceneWarningDiagnostic } from "./diagnostics.js";
+const SAFE_ID = /^[a-z0-9][a-z0-9._-]*$/u;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.trim().length > 0) ? value.map((entry) => entry.trim()) : null;
+}
+function warnUnknownProps(props, allowed, path) {
+  const allowedSet = new Set(allowed);
+  return Object.keys(props).filter((key) => !allowedSet.has(key)).map((key) => sceneWarningDiagnostic("scene.diagram_unknown_prop", `Unknown diagram prop: ${key}.`, `${path}.props.${key}`));
+}
+function propsFor(diagram) {
+  return isRecord(diagram.props) ? diagram.props : {};
+}
+function titleProp(props, fallback) {
+  return typeof props.title === "string" && props.title.trim() ? props.title.trim() : fallback;
+}
+function operationLifecycle() {
+  return {
+    id: "OperationLifecycleDiagram",
+    phase: 7,
+    status: "available",
+    summary: "Animate Treeseed platform operation status progression.",
+    component: "OperationLifecycleDiagram",
+    kind: "operation-lifecycle",
+    defaultDurationSeconds: 12,
+    validateProps({ diagram, path }) {
+      const props = propsFor(diagram);
+      const diagnostics = warnUnknownProps(props, ["states", "activeState", "title"], path);
+      const states = stringArray(props.states);
+      if (!states || states.length === 0) diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "OperationLifecycleDiagram requires a non-empty string array prop: states.", `${path}.props.states`));
+      if (props.activeState !== void 0 && typeof props.activeState !== "string") diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "OperationLifecycleDiagram activeState must be a string.", `${path}.props.activeState`));
+      if (props.title !== void 0 && typeof props.title !== "string") diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "OperationLifecycleDiagram title must be a string.", `${path}.props.title`));
+      if (states && typeof props.activeState === "string" && !states.includes(props.activeState)) diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", `OperationLifecycleDiagram activeState must be one of: ${states.join(", ")}.`, `${path}.props.activeState`));
+      return diagnostics;
+    },
+    normalizeProps({ diagram }) {
+      const props = propsFor(diagram);
+      return {
+        title: titleProp(props, "Operation lifecycle"),
+        states: stringArray(props.states) ?? ["queued", "claimed", "running", "verified", "completed"],
+        ...typeof props.activeState === "string" ? { activeState: props.activeState } : {}
+      };
+    }
+  };
+}
+function reconciliationLifecycle() {
+  return {
+    id: "ReconciliationLifecycleDiagram",
+    phase: 7,
+    status: "available",
+    summary: "Animate exact-state reconciliation from refresh through persist.",
+    component: "ReconciliationLifecycleDiagram",
+    kind: "reconciliation-lifecycle",
+    defaultDurationSeconds: 14,
+    validateProps({ diagram, path }) {
+      const props = propsFor(diagram);
+      const diagnostics = warnUnknownProps(props, ["stages", "title"], path);
+      if (props.stages !== void 0 && !stringArray(props.stages)) diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "ReconciliationLifecycleDiagram stages must be a non-empty string array.", `${path}.props.stages`));
+      if (props.title !== void 0 && typeof props.title !== "string") diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "ReconciliationLifecycleDiagram title must be a string.", `${path}.props.title`));
+      return diagnostics;
+    },
+    normalizeProps({ diagram }) {
+      const props = propsFor(diagram);
+      return {
+        title: titleProp(props, "Reconciliation lifecycle"),
+        stages: stringArray(props.stages) ?? ["refresh", "diff", "plan", "validate", "apply", "refresh", "verify", "persist"]
+      };
+    }
+  };
+}
+function devRuntimeTopology() {
+  return {
+    id: "DevRuntimeTopologyDiagram",
+    phase: 7,
+    status: "available",
+    summary: "Animate managed local dev web, API, and operations-runner topology.",
+    component: "DevRuntimeTopologyDiagram",
+    kind: "dev-runtime-topology",
+    defaultDurationSeconds: 12,
+    validateProps({ diagram, path }) {
+      const props = propsFor(diagram);
+      const diagnostics = warnUnknownProps(props, ["surfaces", "links", "title"], path);
+      const surfaceIds = /* @__PURE__ */ new Set(["web", "api", "operations-runner"]);
+      if (props.surfaces !== void 0) {
+        if (!Array.isArray(props.surfaces)) {
+          diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "DevRuntimeTopologyDiagram surfaces must be an array.", `${path}.props.surfaces`));
+        } else {
+          surfaceIds.clear();
+          props.surfaces.forEach((surface, index) => {
+            if (!isRecord(surface) || typeof surface.id !== "string" || !SAFE_ID.test(surface.id)) {
+              diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "DevRuntimeTopologyDiagram surface ids must be filesystem-safe strings.", `${path}.props.surfaces[${index}].id`));
+              return;
+            }
+            surfaceIds.add(surface.id);
+          });
+        }
+      }
+      if (props.links !== void 0) {
+        if (!Array.isArray(props.links)) {
+          diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "DevRuntimeTopologyDiagram links must be an array.", `${path}.props.links`));
+        } else {
+          props.links.forEach((link, index) => {
+            if (!isRecord(link) || typeof link.from !== "string" || typeof link.to !== "string" || !surfaceIds.has(link.from) || !surfaceIds.has(link.to)) {
+              diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "DevRuntimeTopologyDiagram links must reference known surface ids.", `${path}.props.links[${index}]`));
+            }
+          });
+        }
+      }
+      if (props.title !== void 0 && typeof props.title !== "string") diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "DevRuntimeTopologyDiagram title must be a string.", `${path}.props.title`));
+      return diagnostics;
+    },
+    normalizeProps({ diagram }) {
+      const props = propsFor(diagram);
+      return {
+        title: titleProp(props, "Managed dev topology"),
+        surfaces: Array.isArray(props.surfaces) ? props.surfaces : [
+          { id: "web", label: "Web", kind: "Astro" },
+          { id: "api", label: "API", kind: "Node" },
+          { id: "operations-runner", label: "Operations Runner", kind: "worker" }
+        ],
+        links: Array.isArray(props.links) ? props.links : [
+          { from: "web", to: "api", label: "HTTP" },
+          { from: "api", to: "operations-runner", label: "operations" }
+        ]
+      };
+    }
+  };
+}
+function sceneExecutionTimeline() {
+  return {
+    id: "SceneExecutionTimelineDiagram",
+    phase: 7,
+    status: "available",
+    summary: "Animate scene chapters, segments, steps, and checkpoints.",
+    component: "SceneExecutionTimelineDiagram",
+    kind: "scene-execution-timeline",
+    defaultDurationSeconds: 10,
+    validateProps({ diagram, path }) {
+      const props = propsFor(diagram);
+      const diagnostics = warnUnknownProps(props, ["title", "showCheckpoints", "showSegments"], path);
+      if (props.title !== void 0 && typeof props.title !== "string") diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "SceneExecutionTimelineDiagram title must be a string.", `${path}.props.title`));
+      if (props.showCheckpoints !== void 0 && typeof props.showCheckpoints !== "boolean") diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "SceneExecutionTimelineDiagram showCheckpoints must be a boolean.", `${path}.props.showCheckpoints`));
+      if (props.showSegments !== void 0 && typeof props.showSegments !== "boolean") diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "SceneExecutionTimelineDiagram showSegments must be a boolean.", `${path}.props.showSegments`));
+      return diagnostics;
+    },
+    normalizeProps({ diagram, run }) {
+      const props = propsFor(diagram);
+      const report = run;
+      return {
+        title: titleProp(props, "Scene execution timeline"),
+        showCheckpoints: typeof props.showCheckpoints === "boolean" ? props.showCheckpoints : true,
+        showSegments: typeof props.showSegments === "boolean" ? props.showSegments : true,
+        chapters: report?.chapters ?? [],
+        segments: report?.segments ?? [],
+        steps: report?.steps ?? [],
+        checkpoints: report?.checkpoints ?? [],
+        failedStep: report?.failedStep ?? null
+      };
+    }
+  };
+}
+function createBuiltInTreeseedSceneDiagramProvider() {
+  const diagrams = [
+    operationLifecycle(),
+    reconciliationLifecycle(),
+    devRuntimeTopology(),
+    sceneExecutionTimeline()
+  ];
+  return {
+    id: "treeseed-remotion-diagrams",
+    phase: 7,
+    status: "available",
+    summary: "Operation, reconciliation, dev topology, and scene execution timeline diagrams.",
+    diagrams: Object.fromEntries(diagrams.map((definition) => [definition.component, definition]))
+  };
+}
+export {
+  createBuiltInTreeseedSceneDiagramProvider
+};

package/dist/scenes/diagram-validation.d.ts

@@ -0,0 +1,22 @@
+import type { TreeseedSceneDiagnostic, TreeseedSceneDiagramDefinition, TreeseedSceneManifest, TreeseedScenePluginRegistry, TreeseedSceneRenderDiagram, TreeseedSceneRunReport, TreeseedSceneTimelineEvent } from './types.js';
+export declare function resolveTreeseedSceneDiagramDefinition(input: {
+    component: string;
+    registry: TreeseedScenePluginRegistry;
+}): TreeseedSceneDiagramDefinition | null;
+export declare function treeseedSceneDiagramPluginId(input: {
+    component: string;
+    registry: TreeseedScenePluginRegistry;
+}): string | null;
+export declare function validateTreeseedSceneDiagrams(input: {
+    scene: TreeseedSceneManifest;
+    registry?: TreeseedScenePluginRegistry;
+}): TreeseedSceneDiagnostic[];
+export declare function buildTreeseedSceneRenderDiagrams(input: {
+    scene: TreeseedSceneManifest;
+    run: TreeseedSceneRunReport;
+    timeline: TreeseedSceneTimelineEvent[];
+    registry: TreeseedScenePluginRegistry;
+}): {
+    diagrams: TreeseedSceneRenderDiagram[];
+    diagnostics: TreeseedSceneDiagnostic[];
+};

package/dist/scenes/diagram-validation.js

@@ -0,0 +1,74 @@
+import { sceneErrorDiagnostic } from "./diagnostics.js";
+import { createBuiltInTreeseedScenePluginRegistry } from "./registry.js";
+const PLACEMENTS = /* @__PURE__ */ new Set(["overlay", "interstitial", "standalone"]);
+function resolveTreeseedSceneDiagramDefinition(input) {
+  for (const provider of input.registry.diagrams.values()) {
+    const definition = provider.diagrams[input.component];
+    if (definition) return definition;
+  }
+  return null;
+}
+function treeseedSceneDiagramPluginId(input) {
+  for (const [providerId, provider] of input.registry.diagrams.entries()) {
+    if (provider.diagrams[input.component]) return input.registry.diagramPlugins.get(providerId) ?? null;
+  }
+  return null;
+}
+function validateTreeseedSceneDiagrams(input) {
+  const registry = input.registry ?? createBuiltInTreeseedScenePluginRegistry();
+  const diagnostics = [];
+  input.scene.diagrams.forEach((diagram, index) => {
+    const path = `diagrams[${index}]`;
+    const definition = resolveTreeseedSceneDiagramDefinition({ component: diagram.component, registry });
+    if (!definition) {
+      diagnostics.push(sceneErrorDiagnostic("scene.diagram_unknown_component", `Unknown scene diagram component: ${diagram.component}.`, `${path}.component`));
+      return;
+    }
+    if (diagram.renderer !== "remotion") {
+      diagnostics.push(sceneErrorDiagnostic("scene.diagram_renderer_mismatch", `Diagram component ${diagram.component} requires renderer "remotion".`, `${path}.renderer`));
+    }
+    if (!PLACEMENTS.has(diagram.placement)) {
+      diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_placement", `Unknown diagram placement: ${diagram.placement}.`, `${path}.placement`));
+    }
+    if (diagram.durationSeconds !== void 0 && (!Number.isFinite(diagram.durationSeconds) || diagram.durationSeconds <= 0)) {
+      diagnostics.push(sceneErrorDiagnostic("scene.diagram_invalid_props", "Diagram durationSeconds must be a positive finite number.", `${path}.durationSeconds`));
+    }
+    diagnostics.push(...definition.validateProps({ diagram, path }));
+  });
+  return diagnostics;
+}
+function stepOffset(stepId, timeline) {
+  const exact = timeline.find((event) => event.stepId === stepId && (event.type === "step.start" || event.type === "step.started"));
+  if (exact) return exact.offsetMs;
+  return timeline.find((event) => event.stepId === stepId)?.offsetMs ?? null;
+}
+function buildTreeseedSceneRenderDiagrams(input) {
+  const diagnostics = validateTreeseedSceneDiagrams({ scene: input.scene, registry: input.registry });
+  const renderDiagrams = [];
+  if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) return { diagrams: renderDiagrams, diagnostics };
+  input.scene.diagrams.forEach((diagram) => {
+    const definition = resolveTreeseedSceneDiagramDefinition({ component: diagram.component, registry: input.registry });
+    if (!definition) return;
+    renderDiagrams.push({
+      id: diagram.id,
+      renderer: diagram.renderer,
+      component: diagram.component,
+      kind: definition.kind,
+      placement: diagram.placement,
+      at: diagram.at,
+      startOffsetMs: stepOffset(diagram.at, input.timeline),
+      durationSeconds: diagram.durationSeconds ?? definition.defaultDurationSeconds,
+      props: definition.normalizeProps({ diagram, scene: input.scene, run: input.run }),
+      objects: diagram.objects ?? [],
+      ...diagram.motion ? { motion: diagram.motion } : {},
+      ...diagram.style ? { style: diagram.style } : {}
+    });
+  });
+  return { diagrams: renderDiagrams, diagnostics };
+}
+export {
+  buildTreeseedSceneRenderDiagrams,
+  resolveTreeseedSceneDiagramDefinition,
+  treeseedSceneDiagramPluginId,
+  validateTreeseedSceneDiagrams
+};

package/dist/scenes/environment.d.ts

@@ -0,0 +1,2 @@
+import type { TreeseedSceneEnvironmentPrepareOptions, TreeseedSceneEnvironmentPrepareReport } from './types.js';
+export declare function prepareTreeseedSceneEnvironment(input: TreeseedSceneEnvironmentPrepareOptions): Promise<TreeseedSceneEnvironmentPrepareReport>;

package/dist/scenes/environment.js

@@ -0,0 +1,65 @@
+import { readTreeseedDevInstance, startTreeseedManagedDev } from "../local-dev/managed-dev.js";
+import { collectTreeseedDeploymentReadiness } from "../workflow-support.js";
+import { sceneErrorDiagnostic, sceneWarningDiagnostic } from "./diagnostics.js";
+function healthUrl(instance) {
+  const candidate = instance;
+  return candidate?.health?.find((entry) => entry.kind === "http" && typeof entry.url === "string")?.url ?? null;
+}
+function running(instance) {
+  return Boolean(instance?.running);
+}
+async function prepareTreeseedSceneEnvironment(input) {
+  const diagnostics = [];
+  let readiness = null;
+  try {
+    readiness = collectTreeseedDeploymentReadiness({ tenantRoot: input.projectRoot, environment: input.environment });
+    if (input.environment !== "local" && readiness?.ok === false) {
+      diagnostics.push(sceneErrorDiagnostic("scene.readiness_failed", `Treeseed ${input.environment} readiness failed. Run trsd ready ${input.environment} --json for details.`, "setup.readiness"));
+    }
+  } catch (error) {
+    const diagnostic = sceneWarningDiagnostic("scene.readiness_unavailable", error instanceof Error ? error.message : String(error ?? "Readiness could not be collected."), "setup.readiness");
+    if (input.environment === "local") diagnostics.push(diagnostic);
+    else diagnostics.push({ ...diagnostic, severity: "error", code: "scene.readiness_failed" });
+  }
+  const requested = input.environment === "local" && input.scene.setup.dev?.required === true;
+  const command = input.scene.setup.dev?.command;
+  if (command) {
+    diagnostics.push(sceneWarningDiagnostic("scene.setup_command_not_executed", `Scene setup command is informational in Phase 3 and was not executed: ${command}`, "setup.dev.command"));
+  }
+  let reused = false;
+  let started = false;
+  let instances = [];
+  let baseUrl = null;
+  if (requested) {
+    const existing = readTreeseedDevInstance({ cwd: input.projectRoot, surface: "web" });
+    const existingApi = readTreeseedDevInstance({ cwd: input.projectRoot, surface: "api" });
+    if (running(existing) && healthUrl(existing) && running(existingApi) && healthUrl(existingApi)) {
+      reused = true;
+      instances = [existing, existingApi];
+      baseUrl = healthUrl(existing);
+    } else {
+      try {
+        const result = await startTreeseedManagedDev({ cwd: input.projectRoot, surfaces: "web,api,operations-runner", webRuntime: "local", env: input.env });
+        instances = result.instances;
+        const web = result.instances.find((entry) => entry.surface === "web" || entry.id === "web");
+        started = Boolean(web && running(web));
+        baseUrl = web ? healthUrl(web) : null;
+        if (!started || !baseUrl) {
+          diagnostics.push(sceneErrorDiagnostic("scene.local_dev_start_failed", "Local dev was requested but the managed web surface did not start.", "setup.dev"));
+        }
+      } catch (error) {
+        diagnostics.push(sceneErrorDiagnostic("scene.local_dev_start_failed", error instanceof Error ? error.message : String(error ?? "Local dev start failed."), "setup.dev"));
+      }
+    }
+  }
+  return {
+    ok: !diagnostics.some((entry) => entry.severity === "error"),
+    environment: input.environment,
+    readiness,
+    dev: { requested, reused, started, instances, baseUrl },
+    diagnostics
+  };
+}
+export {
+  prepareTreeseedSceneEnvironment
+};

package/dist/scenes/evidence-bundle.d.ts

@@ -0,0 +1,5 @@
+import type { TreeseedSceneEvidenceArtifact, TreeseedSceneEvidenceManifest, TreeseedSceneEvidencePaths } from './types.js';
+export declare function writeTreeseedSceneEvidenceBundle(input: {
+    manifest: TreeseedSceneEvidenceManifest;
+    paths: TreeseedSceneEvidencePaths;
+}): TreeseedSceneEvidenceArtifact[];

package/dist/scenes/evidence-bundle.js

@@ -0,0 +1,42 @@
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+function safeBundlePath(bundleRoot, relativePath) {
+  return join(bundleRoot, relativePath.replace(/^(\.\.[/\\])+/u, "").replace(/^[/\\]+/u, ""));
+}
+function writeTreeseedSceneEvidenceBundle(input) {
+  if (!input.paths.bundleRoot || !input.paths.bundleManifestPath) return input.manifest.artifacts;
+  const copied = [];
+  for (const artifact of input.manifest.artifacts) {
+    if (!artifact.includedInBundle || !existsSync(artifact.path)) {
+      copied.push(artifact);
+      continue;
+    }
+    const targetPath = safeBundlePath(input.paths.bundleRoot, artifact.relativePath);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    copyFileSync(artifact.path, targetPath);
+    copied.push({
+      ...artifact,
+      path: targetPath,
+      relativePath: artifact.relativePath
+    });
+  }
+  const bundleManifest = {
+    schemaVersion: "treeseed.scene.evidence-bundle/v1",
+    generatedAt: input.manifest.generatedAt,
+    sceneId: input.manifest.summary.sceneId,
+    sourceRunId: input.manifest.summary.runId,
+    target: input.manifest.target,
+    bundlePolicy: input.manifest.bundlePolicy,
+    artifacts: copied
+  };
+  writeJson(input.paths.bundleManifestPath, bundleManifest);
+  return copied;
+}
+export {
+  writeTreeseedSceneEvidenceBundle
+};

package/dist/scenes/evidence-report.d.ts

@@ -0,0 +1,10 @@
+import type { TreeseedSceneDiagnostic, TreeseedSceneEvidenceManifest, TreeseedSceneEvidencePaths } from './types.js';
+export declare function formatTreeseedSceneEvidenceMarkdownReport(manifest: TreeseedSceneEvidenceManifest): string;
+export declare function writeTreeseedSceneEvidenceReport(input: {
+    manifest: TreeseedSceneEvidenceManifest;
+    paths: TreeseedSceneEvidencePaths;
+}): void;
+export declare function appendTreeseedSceneEvidencePaths(input: {
+    runPath: string;
+    paths: TreeseedSceneEvidencePaths;
+}): TreeseedSceneDiagnostic[];

package/dist/scenes/evidence-report.js

@@ -0,0 +1,73 @@
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { sceneWarningDiagnostic } from "./diagnostics.js";
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+function writeText(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, value, "utf8");
+}
+function formatTreeseedSceneEvidenceMarkdownReport(manifest) {
+  const lines = [
+    `# Treeseed Scene Evidence: ${manifest.summary.sceneId ?? "(unknown scene)"}`,
+    "",
+    `Scene: ${manifest.summary.sceneId ?? "(unknown)"}`,
+    `Source run: ${manifest.summary.runId ?? "(unknown)"}`,
+    `Target: ${manifest.target}`,
+    `Bundle: ${manifest.bundlePolicy}`,
+    `Workflow: ${manifest.summary.workflowStatus}`,
+    `Failed step: ${manifest.summary.failedStep ?? "(none)"}`,
+    `Steps: ${manifest.summary.stepCounts.passed} passed, ${manifest.summary.stepCounts.failed} failed, ${manifest.summary.stepCounts.skipped} skipped`,
+    `Chapters: ${manifest.summary.chapters}`,
+    `Segments: ${manifest.summary.segments}`,
+    `Checkpoints: ${manifest.summary.checkpoints}`,
+    `Rendered videos: ${manifest.summary.renderedVideos}`,
+    `Training outputs: ${manifest.summary.trainingOutputs ? "yes" : "no"}`,
+    "",
+    "## Artifacts",
+    "",
+    "| Kind | Path | Bundle | SHA-256 |",
+    "| --- | --- | --- | --- |",
+    ...manifest.artifacts.map((artifact) => [
+      `| ${artifact.kind}`,
+      artifact.relativePath,
+      artifact.includedInBundle ? "included" : artifact.redactionStatus,
+      artifact.sha256 ?? "(none)",
+      "|"
+    ].join(" | ")),
+    "",
+    "## Recommendations",
+    "",
+    ...manifest.recommendations.length > 0 ? manifest.recommendations.map((recommendation) => `- ${recommendation.severity.toUpperCase()} ${recommendation.reason}: \`${recommendation.command}\``) : ["- No follow-up recommendations."],
+    ""
+  ];
+  return lines.join("\n");
+}
+function writeTreeseedSceneEvidenceReport(input) {
+  writeJson(input.paths.manifestPath, input.manifest);
+  writeText(input.paths.reportPath, formatTreeseedSceneEvidenceMarkdownReport(input.manifest));
+}
+function appendTreeseedSceneEvidencePaths(input) {
+  try {
+    if ((statSync(input.runPath).mode & 146) === 0) {
+      throw new Error("run.json is not writable.");
+    }
+    const run = JSON.parse(readFileSync(input.runPath, "utf8"));
+    writeJson(input.runPath, {
+      ...run,
+      evidencePaths: input.paths,
+      logs: run.logs ? { ...run.logs, evidence: input.paths.evidenceRoot } : run.logs
+    });
+    return [];
+  } catch (error) {
+    return [sceneWarningDiagnostic("scene.evidence_run_update_failed", `Evidence artifacts were written but run.json could not be updated. ${error instanceof Error ? error.message : String(error ?? "")}`.trim(), "run.json")];
+  }
+}
+export {
+  appendTreeseedSceneEvidencePaths,
+  formatTreeseedSceneEvidenceMarkdownReport,
+  writeTreeseedSceneEvidenceReport
+};

package/dist/scenes/evidence.d.ts

@@ -0,0 +1,16 @@
+import type { TreeseedSceneEvidenceBundlePolicy, TreeseedSceneEvidenceManifest, TreeseedSceneEvidenceOptions, TreeseedSceneEvidencePaths, TreeseedSceneEvidenceReport, TreeseedSceneEvidenceTarget, TreeseedSceneManifest, TreeseedSceneRunReport, TreeseedSceneTimelineEvent } from './types.js';
+export declare function buildTreeseedSceneEvidenceManifest(input: {
+    scene: TreeseedSceneManifest;
+    run: TreeseedSceneRunReport;
+    timeline: TreeseedSceneTimelineEvent[];
+    runRoot: string;
+    target?: TreeseedSceneEvidenceTarget;
+    bundlePolicy?: TreeseedSceneEvidenceBundlePolicy;
+    bundle?: TreeseedSceneEvidenceBundlePolicy;
+    timestamp?: string;
+}): TreeseedSceneEvidenceManifest;
+export declare function writeTreeseedSceneEvidence(input: {
+    runRoot: string;
+    manifest: TreeseedSceneEvidenceManifest;
+}): TreeseedSceneEvidencePaths;
+export declare function generateTreeseedSceneEvidence(input: TreeseedSceneEvidenceOptions): TreeseedSceneEvidenceReport;