stillmade-sdk 0.1.42 → 0.1.44

package/docs/project-types/hosted-review.md

@@ -0,0 +1,115 @@
+# Review hosted Project Types
+
+A Project Type can include reviewed `text.generate`, `audio.speech`, and
+`image.generate` Blocks alongside local recipe/JavaScript Blocks and StillMade
+workspaces. Import checks two separate things: whether every embedded package is
+safe and reviewed, and which parts of the connected workflow have actually run.
+Passing independent Block fixtures does not prove their connected production flow.
+
+### Prepare portable source
+
+The source contains ordinary pinned packages and connections. It never contains
+account receipts, chosen payment methods, API keys or provider approval. For
+example, run this from the extracted SDK directory to create a script-to-speech
+Project Type using the included complete Block examples:
+
+```js
+import {writeFile} from 'node:fs/promises';
+import {textGenerate} from './packages/block-sdk/capability-example.js';
+import {audioSpeech} from './packages/block-sdk/speech-example.js';
+
+const type = {
+  schemaVersion: 1,
+  id: 'creator.script-and-speech',
+  version: '1.0.0',
+  name: 'Script and speech',
+  description: 'Draft a short narration script and turn it into reviewed speech.',
+  license: 'MIT',
+  stages: [
+    {id: 'draft', blockId: textGenerate.manifest.id, version: '1.0.0', label: 'Draft narration'},
+    {id: 'voice', blockId: audioSpeech.manifest.id, version: '1.0.0', label: 'Narrate script'}
+  ],
+  packages: [textGenerate, audioSpeech],
+  connections: [
+    {from: {stage: 'draft', port: 'script'}, to: {stage: 'voice', port: 'script'}}
+  ]
+};
+await writeFile('script-and-speech.stillmade.json', JSON.stringify(type, null, 2), {flag: 'wx'});
+```
+
+This writes source only. It has not generated narration or speech. The offline
+validator checks its structure, versions and typed connections. Local fixture
+checks still execute in isolation; hosted fixture expectations require an account
+review in StillMade. Source packaging does not install a package or authorize a
+provider call.
+
+### Review in StillMade
+
+Open **Import package** and select the JSON or ZIP. Review each hosted Block with
+the model, payment method, voice or image quality selected in the host controls.
+An exact saved import review can be shown and accepted without new generation.
+Running a new review still requires its displayed quote and explicit confirmation
+for the fixtures and separate sample. Review actual text, audio or images before
+accepting the evidence. Source, account or selection changes invalidate reuse.
+
+Every embedded hosted package needs a matching review, including packages used
+only by disabled Steps or currently unused packages. Repeated placements of an
+unchanged package share one package review. They do not share a production run:
+each placement's actual connected input still requires its own execution approval.
+
+After package reviews, StillMade runs the local checks and the portions of the
+sample flow that can execute locally. An enabled hosted Step is marked unexecuted;
+its dependent Steps wait for its real output. They never receive the hosted
+Block's independent fixture sample as a substitute. Missing independent context,
+invalid connections and failing local code still prevent import. A genuinely
+disabled Step or a valid conditional bypass keeps its ordinary workflow behavior.
+
+The report distinguishes `passed` (package admission) from `workflowComplete`
+(all enabled connected Steps completed). **Confirm Import** installs the reviewed
+source, and the report continues to show any required workflow rehearsal. A new
+release or another account's installation rechecks the receipts and current
+source. ComfyUI-containing Project Types use their separate connection-bound
+review map, described below.
+Unattended hosted automation and a single complete hosted-workflow execution proof
+remain separate work; an import report must not claim either one.
+
+### Host review envelope
+
+The authenticated host passes `typeCapabilityReviews` alongside `content` to
+`POST /api/blocks/imports/review` and `/api/blocks/imports`, and alongside the
+normal release/install fields to `/api/blocks/releases` and `/api/blocks/install`.
+It is a plain object with exactly the distinct embedded hosted package digests:
+
+```js
+const typeCapabilityReviews = {
+  [exactPackageDigest]: {
+    receiptId: verifiedReview.receiptId,
+    selection: verifiedReview.selection
+  }
+};
+```
+
+Use the SDK `digest(package)` on the entire exact package. The map has at most
+100 entries and is at most 64 KiB as JSON. Each entry contains only `receiptId`
+and the existing exact host `selection`. Unknown/missing digests, another
+account's receipts, changed source, expired receipts or invalid retained media
+are rejected. The server rechecks before writing the import, release or install;
+these checks never generate output or charge again. They do not extend a review's
+one-hour standalone import expiry. Project-only expired evidence cannot be used.
+
+The server returns the sanitized map in the account review report, outside the
+portable source. A host may use `verifyHostedProjectTypePackages` from
+`packages/block-platform/hosted-type-reviews.js` with its trusted authenticated
+receipt verifier to obtain the opaque `verifiedHostedPackages` option for
+`testProjectType` and `previewProjectType`. Guest JSON cannot construct this
+in-memory proof. The helper itself does not authenticate receipts; ordinary Block
+authors should use StillMade's review UI.
+
+### Retained samples and setup
+
+Saved imports, releases and hosted installations retain their reviewed sample
+media through account-bound server reports. Installed review metadata stores
+no extra source copy and grants no release access. Removing team access still stops new private source downloads.
+Retaining a historical sample does not extend its import-approval expiry. Legacy
+installations without a saved report are not retroactively assigned a receipt.
+The current storage and encrypted BYOK vault are reused.

package/docs/project-types/onboarding.md

@@ -0,0 +1,75 @@
+# Project defaults and onboarding
+
+### Typed shared inputs
+
+The optional `projectInputs` array declares up to 32 shared input contracts using
+`key`, `type`, `semantic`, `required` and `description`, plus the usual optional
+schema, accepted meanings, source policy, default, sensitivity, freshness,
+cardinality, batching and numeric limits. Keys are unique lowercase identifiers
+up to 64 characters. For example:
+
+```json
+{"projectInputs":[{"key":"brand_tone","type":"text","semantic":"brand_tone","required":true,"description":"How the brand should sound","sources":["default","user"],"default":"Clear and friendly"}]}
+```
+
+Defaults must validate against their contracts and permit the `default` source.
+Credential-sensitive defaults are rejected. New projects initialize these values
+in typed context with Project Type provenance; matching Block inputs must allow
+`project` sources. Existing values are never overwritten by initialization.
+Other equally ranked ready project values take precedence over these fallback
+records unless a source preference explicitly selects the default. The composer
+and connected preview use the defaults too; explicit sample values,
+settings and connections remain authoritative. Freshness limits produce expiring
+context values. These contracts grant no permissions or execution authority.
+
+Native controls can inspect or replace the declarations. The visual setup editor
+can add shared information from project-capable Block requirements, preserving
+their types, meanings and schemas, then edit descriptions, required flags and
+defaults. Advanced contract editing handles custom declarations and complex
+values. Edits stay local until Apply shared inputs; validation is shared with
+native edits. Missing values do not create an upfront questionnaire. The next
+local recipe/JavaScript Block can request a uniquely matching shared input through
+the existing reviewed-answer flow. The declaration controls user/Chat sources;
+both its contract and the consuming Block's contract must accept the answer.
+Saved answers carry workflow provenance and source revisions, and permitted
+Blocks can reuse them. Ambiguous declarations are not chosen automatically.
+The existing saved-answer editor can update reviewed shared answers and newly
+initialized defaults against an unchanged declaration and a current permitted
+consumer. Edits require the current revision, remove default fallback priority,
+and mark dependent results stale. Credential-sensitive and dependency-derived
+records are not exposed in this editor. Older unsigned defaults are preserved
+without being silently enrolled in editing. Richer value pickers and hosted-Block
+collection remain unfinished.
+Existing releases are not rewritten.
+
+Connected previews accept shared sample answers at `context.sharedInputs`, keyed
+by the declared shared-input key. The preview form uses the existing typed-answer
+dialogs; complex values can use the sample context JSON. Samples must satisfy
+their declarations and permit user answers; credential-sensitive samples are
+rejected. They replace matching template defaults only in the preview registry,
+and matching consumers must still allow project sources. Explicit Step inputs
+and connected results retain precedence. Sample answers are never saved into the
+Project Type or a real project. Existing sample digests and server rehearsal
+replay include the whole context, so shared samples follow the same verification
+path. This does not simulate trusted connections or allow missing hosted results.
+
+A Project Type can declare project defaults and up to eight setup questions. These are optional additions to the schema-1 Project Type contract; they do not replace protected Chat, configure provider credentials or start production work.
+
+```json
+{
+  "defaults": {"aspectRatio": "9:16", "brief": "Create a short product launch video."},
+  "onboarding": [
+    {"id": "product", "label": "What is the product?", "type": "text", "required": true},
+    {"id": "audience", "label": "Who is it for?", "type": "textarea"},
+    {"id": "tone", "label": "Tone", "type": "select", "options": ["Clear and direct", "Playful"], "default": "Clear and direct"}
+  ]
+}
+```
+
+Merge these fields into an existing valid Project Type with `schemaVersion`, `id`, `version`, `name`, `description` and its enabled `stages`. This fragment is not a standalone package.
+
+`defaults.aspectRatio` accepts `16:9`, `9:16` or `1:1`; `defaults.brief` is at most 4,000 characters. Question IDs are unique lowercase identifiers up to 40 characters. Labels are at most 120 characters. Text and textarea answers are at most 1,000 characters. A select question declares 2–12 unique options of at most 120 characters; its default must match an option. `required` is optional and boolean.
+
+The Project Type Builder exposes these fields under **Project defaults & starting questions**. Using the Project Type opens one project setup dialog. The host records the chosen project name and format, and retains the brief plus labeled answers in the existing project's production context (`bible.extraInfo`). Script Writer receives this brief. Answers are project data, not edits to a marketplace release or its version identity; they are not published or sent to acquisition analytics. Read Blueprint/project context only through the permissions already documented by the SDK.
+
+The empty Project Type starter is an editable draft. Add an enabled Block before validation, runtime execution, or publication; empty drafts are never installable releases.

package/docs/project-types/running.md

@@ -0,0 +1,309 @@
+# Run connected steps
+
+### Inspect a specific run
+
+In a project's Flow view, select a live run to see its captured input connections,
+or select a historical attempt to inspect its saved evidence. Current connections
+remain a separate planned view. Missing captured input records are shown as
+unavailable; the host does not reconstruct them from today's source choices.
+
+**Ask chat about this run** captures the selected receipt, including batch item,
+attempt and loop pass when recorded. The native controller resolves that receipt
+again through authorized saved-project inspection. Unsaved or evicted receipts
+are unavailable to that saved-project read; another attempt is never substituted.
+Legacy run-only targets are accepted only when exactly one receipt matches.
+
+Host integrations use `projectFlowRunReceiptIdentity(record)` from
+`packages/block-platform/flow-inspection.js` for the bounded
+`receipt:<placementId>:<identity>` conversation scope. This is a locator, not an
+access grant. Resolve it within the authorized project's placement history and
+require exactly one match. Inspect/read operations neither run a Block nor change
+its source. Existing retained-history limits still apply.
+
+### Failure and recovery evidence
+
+Flow distinguishes `EXECUTION_FAILED` from `RESULT_DELIVERY_FAILED` (a result
+returned, but delivery to the project was interrupted) and `RESULT_SAVE_FAILED` (a result
+returned, but project saving was not confirmed). The latter states show **Needs
+recovery** rather than implying that generation produced nothing. Recovery must
+use the supported request/result controls before a new paid run is considered.
+
+The original failed-attempt record remains in history. If a matching provider
+result or exact run/input/item receipt is later retained, its history entry gains
+`recovered: true` and the current failure warning clears. This does not mean a
+retained result was selected. Diagnostics contain bounded codes and duration;
+raw provider messages, prompts and media addresses are excluded.
+
+### Run connected Steps
+
+Inside a Project Type, **Run connected steps** runs the selected recipe or isolated
+JavaScript Step and the following supported connected Steps in workflow order.
+The host captures the exact Project Type, package versions, current settings,
+conditions and connections. Every input comes from current project data, supplied
+values, declared context, or an actual upstream output. Production runs never
+prefill missing values from package test fixtures.
+
+A connected run stops before a manual workspace, a Block requiring separate
+runtime approval, or an unconnected Step. The UI shows the ordered sequence and
+stopping point; it does not ask users to wire a graph. ComfyUI, hosted workspaces
+and generation are not silently dispatched as part of this local sequence. They
+retain their own execution and confirmation paths.
+
+The shared host helper is `packages/block-platform/segment-runner.js`:
+
+```js
+const plan = await planSegment(projectType, canvas, startingStepId);
+const result = await runSegment(plan, {
+  source: selectedSource, // stable source/version identity, when applicable
+  inputs: { [startingStepId]: currentInputs },
+  externalInputs: currentInputsFromOutsideTheSegment,
+  resolveContext: (step, source) => scopedContextFor(step, source),
+  execute: (pkg, input, { signal, check }) => runInTrustedHost(pkg, input, { signal, check }),
+  check: () => verifyCurrentSourceSettingsPermissions(),
+  onStep: record => retainCompletedResult(record),
+  signal,
+});
+```
+
+Custom durable hosts can opt into stateful sandboxed segments with
+`planSegment(type, canvas, startingStepId, {background: true})`. Then call
+`runSegment(plan, {background: true, states, ...options})`, where `states` supplies
+`{version, value}` for **every** stateful Step ID. Background plans pin code,
+settings and connections independently of current memory. The runner never
+mutates the supplied memory. Keep the starting memory snapshot with the job;
+resuming `previousResults` verifies it and refuses changed inputs or memory.
+Persist returned states only in the same transaction as the completed workflow
+results. A failed later Step can retain earlier provisional results, but those
+results must not advance shared memory prematurely. This mode does not authorize
+hosted APIs or ComfyUI. StillMade's scheduled multi-Block service uses this mode with shared Canvas
+editing enabled. It pins the job's starting states, retains provisional
+checkpoints after failures, and commits all memory changes with the completed
+workflow. Selecting a retained result does not apply its memory a second time.
+
+This helper is a host orchestration API, not a capability exposed to guest code.
+The host owns permissions, quarantine checks, media decoding/storage and durable
+adoption. `externalInputs` is keyed by target Step ID then port name, and may only
+fill declared connections from outside the segment. Internal connections always
+use outputs produced earlier in the current run. Context access follows each
+Block's own declarations. A false condition uses the existing typed bypass rule.
+Missing inputs, incompatible roles or stale package/settings pins stop execution.
+Pinned safe connection conversions run in the host before each receiving Block.
+They recheck actual media kinds and authorized current context; a failed
+conversion retains completed upstream results and stops before the receiving
+Step. They do not add a provider call or silently select replacement media.
+
+For an explicit batch selection, a trusted host can set `overridePrimary: true`
+with its already-authorized media `source`. This replaces only the first Step's
+primary input; it must match that input's type and role. Do not put this
+receiver-typed source into `externalInputs` as though it were a raw upstream shot
+or scene. Ordinary connected runs leave the option `false`. The host records
+`primaryInputOverride` when a connection was bypassed, and must preserve that
+choice when validating retained results. This option grants no asset access:
+the host still validates ownership, selection, permissions and source freshness.
+
+The immutable plan has `workflowDigest`, `planDigest`, `startStepId`, ordered
+`steps`, `nextStageId`, and `stopReason`. `result.steps` contains one record per
+completed placement: `stepId`, `packageDigest`, `inputDigest`, `outputs`, `skipped`,
+`at`, and optional host `mediaReceipts`. Identical Blocks at two positions retain
+separate records. On failure, `error.partialResult` retains completed records;
+later Steps are not reported as completed. A host can supply `previousResults`
+only as an ordered prefix whose source, input and package digests still match.
+Cancellation or failure cannot turn a stale partial result into a new success.
+
+## Project handoffs and Flow inspection
+
+Saved shared tasks use `PROJECT_FLOW_OPERATIONS.inspectTasks` (`inspect_project_tasks`, `projects:read`) and `controlTask` (`control_project_task`, separately granted `projects:control` plus `projects:read`). These do not require navigation or a live tab. Inspection returns bounded current task pages or one exact `taskId`. Control accepts pause/takeover/cancel/resume with exact requesterId, taskRevision, instructionRevision, controlEpoch and a unique requestId; current project and connection authority are checked in the transaction. Identical replay returns its original receipt plus current task state without reapplying. Resume queues the existing revalidation process and never approves dispatch, spending or edits; takeover preserves requester/payer. Accepted provider work may still finish after pause/cancel. Native task controls share the coordinator through their existing UI, so their registry `nativeAction` is null. Native and external controls both require the complete observed fence; older native payloads fail with `PROJECT_AI_REFRESH_REQUIRED` instead of changing newer task intent. See [saved task control details](/docs/native-mcp.md#saved-project-task-controls).
+
+`recover_project_capability_request` retrieves one actor-owned project request under `projects:read` + `runs:read` and the existing current edit-access requirement. It verifies retained source/media and an unchanged request ledger before returning bounded, redacted stored outputs with `applied:false` and `selectionChanged:false`. It does not poll a provider, execute, settle, save or select a result. Truncated output envelopes are excerpts. Applying a retained result remains a separate reviewed native recovery action.
+
+The in-app Project Type Builder accepts pinned built-in stages and embedded recipe
+packages in an optional `packages` array. Each stage uses `{id,blockId,version,label}`;
+connections use `{from:{stage,port},to:{stage,port}}`. Duplicate dependencies,
+missing versions, incompatible ports, duplicate input producers, cycles, and root
+chat overrides are rejected. Embedded recipe fixture tests must pass before launch
+or release.
+
+Executable custom types combine embedded SDK processing Blocks with the existing
+production workspaces: Voiceover, Script Writer, Shots, Blueprint, Canvas,
+Image Panels, White Board Motion, animated assets, Editor and Export. The
+workspace adapter selects the existing production screen for each placement.
+Legacy component adapters remain available to saved types; they do not become
+separate workspace listings. Custom JavaScript, recipes and reviewed ComfyUI
+packages open in their own Step workspace. Run them explicitly; navigation never
+triggers paid generation or automatic reruns.
+
+Connections use declared SDK ports or an implemented host port adapter. Canvas
+and Editor workspaces share persistent project documents; listing a port does
+not invent an executable conversion. The builder validates supported handoffs
+and explains when a host port or conversion is not implemented. Script Writer's
+script-to-Voiceover handoff uses the existing narration document. Starting Chat
+remains protected before the configurable flow.
+
+### Project Flow inspection contract
+
+The SDK exports `ProjectFlowTarget`, `projectFlowTarget()` and
+`projectFlowSnapshot()` from `@stillmade/block-sdk`. Targets use stable project,
+placement, input/output, run, attempt and repeated-item IDs; display names and
+screen positions are not target identity. A target may name the `planned`,
+`active_run` or `historical_run` perspective. The snapshot validator checks its
+contract version, definition identity, unique placement IDs, receiving edges,
+completeness flag and documented size bounds. External `inspect_project_flow`
+reads also return a host-computed `snapshotCursor`; use that exact cursor when
+reviewing or applying a saved-project source or result-pin change.
+`redactProjectFlowMediaAddresses()` recursively removes media address fields
+from preview projections before they cross into chat or another client surface.
+When present, a placement's optional `condition` summary contains its input key
+and safe label, bounded field path, supported operator, and the last applied
+outcome (`unknown`, `ran`, or `skipped`). It deliberately omits the comparison
+value. A current skipped conditional output and its receiving input use the
+`skipped` state with no materialized value; this is distinct from a missing
+result. Historical skipped attempts retain a `skipped` history status.
+Saved activity and history may include a bounded `execution` summary: execution
+kind, whether output was captured or omitted by a conditional skip, and a capped
+media-receipt count. It contains no provider run IDs or playable URLs and does
+not establish provider activity for an attempt without a saved Block receipt.
+
+`PROJECT_FLOW_OPERATIONS` maps the shared operation IDs to the native action
+and external tool names. `updateAffected` maps to the existing native
+`update_affected_steps` action; it runs eligible live-workspace Steps, with a
+whole-update budget and separate exact generation review for hosted execution, and has
+no saved-project external tool. `useCompletedResults` maps to the native
+`use_completed_results` action; it adopts retained connected-workflow outputs
+in the live workspace after the host revalidates their receipts, without
+dispatching generation, and has no saved-project external tool. These SDK helpers validate a data shape and map
+operation names; they do not grant access to a project, authorize a mutation,
+or dispatch a Block. Hosts resolve every ID and filter
+labels, previews, candidates and history against current permissions. The
+current saved-project operations are `inspect_project_flow`,
+`list_project_flow_placements`, `list_project_flow_ports`,
+`list_project_flow_history`, `list_project_flow_run_inputs`,
+`read_project_flow_text`, `recover_project_media`,
+`diagnose_project_flow`, `preview_project_flow_source`,
+`change_project_flow_source`, `preview_project_flow_pin`,
+`pin_project_flow_result` and `clear_project_flow_pin`; write operations require
+the current `projects:write` grant and exact preview revisions. They never run
+a Block. Reruns, retries and costly review remain separate authorized actions.
+
+Native `list_placements`, `list_ports` and `list_history` use the same bounded
+projection as those three saved-project page tools. Each requires the exact
+`revision` from its own preceding inspection: native surface revisions and
+saved-project revisions are different and cannot be interchanged. A placement
+page accepts at most 8 rows; ports and retained history accept at most 16.
+Later pages of `inspect_project_flow` also require `expectedRevision`.
+Membership and project ownership are checked again after saved reads.
+
+For example, after `inspect_project_flow({projectId})` returns `revision`, read
+`list_project_flow_history({projectId, placementId, revision, offset:0, limit:8})`
+and continue with the returned `nextOffset`. Each entry includes a `receiptId`
+and `targetKey` identifying the exact attempt/item, plus recorded input evidence.
+Use `targetKey` for chat receipt targeting; several entries may share `runId`.
+`historyComplete:false` distinguishes incomplete retained history from the end
+of a page. `retainedHistoryComplete:false` still applies at the last page; this
+operation cannot recover evicted records or missing historical input evidence.
+`inputsTruncated:true` means only a bounded subset of captured input identities
+was included. The receipt exposes `inputsCount`, `inputsRevision`,
+`inputsNextOffset` and `inputsRetainedComplete`. Use native `list_run_inputs` or
+external `list_project_flow_run_inputs` with `{placementId, receiptId,
+revision: inputsRevision, offset, limit}` (plus `projectId` externally) to read
+at most 16 named captured-input identities per page. This captured-input
+revision is different from the surface/Flow revision. Every page rechecks the
+exact retained receipt and current read permission; changes beyond the initial
+64-input projection also invalidate its revision. A source's present selection
+never replaces the recorded identity. Follow `nextOffset` until null; a final
+page with `retainedComplete:false` still indicates missing original evidence.
+The run capture stores at most 128 named inputs. A capture at that limit may
+have omitted identities and is conservatively marked incomplete. Preview
+attempts also have a 64-input cap and a byte limit. An older preview may have
+retained fewer identities than the original run; paging cannot recover those
+lost entries. Nested collection member identities
+remain bounded within each input; this operation pages named inputs, not raw
+values, full text, or the members of captured collections. The historical
+inspector's Previous/Next inputs controls keep its map on that exact input page. None of these reads starts work, applies results, or proves media
+playback. The native summary exposes `historyTotal` and `historyNextOffset` so
+three displayed receipts are never reported as the whole retained history.
+
+Retained unselected results have a separate read-only inventory. The Result tab
+shows eight candidates at a time. Use native `list_retained_results` or external
+`list_project_flow_retained_results` with `{placementId, revision:
+unusedResultsRevision, offset, limit}` (plus `projectId` externally); list pages
+contain at most eight candidates. Only records still retained for the current
+Block package are included: unused single results, unselected connected results,
+and batch records explicitly marked unused after a source change. The ordinary
+batch picker is separate. `historyComplete:false` means evicted history is not
+recoverable through this inventory, even at its final page.
+
+Each candidate has an exact `candidateId`, `outputDigest`, run/item/attempt
+metadata, and captured-input/output counts and cursors. Native
+`inspect_retained_result` and external `inspect_project_flow_retained_result`
+accept `{placementId, revision: unusedResultsRevision, candidateId, section,
+offset, limit}`. Sections `inputs` and `outputs` page at most 16 identities or
+previews. Sections `text` and `collection` also require `outputKey` and the exact
+preview `path`; text requires its returned `identity` and permits at most 4,000
+characters, collections at most 16 members. Reuse the exact candidate and list
+revision on every page. Changes anywhere in retained records, package or preview
+restrictions invalidate that revision. Inspect fresh state after a conflict.
+Current project read access is rechecked after saved reads; native/UI caches
+reset when the authorized reader changes. External/native results redact media
+addresses. Sensitivity and prior preview restrictions still apply; a restricted
+candidate cannot become inspectable through a later page. Captured inputs remain
+bounded metadata and may be incomplete; nested structured previews disclose
+omitted fields rather than claiming a complete document. These reads never
+select a candidate, restore media, dispatch work, or substitute current output
+for a retained value.
+
+Mapped native Canvas outputs use the installed exact-version host port adapter. Flow can show a saved image, video or text value as `ready` with `observation.kind: "native-canvas-output"` and `runReceiptAvailable:false`. The Inspector labels that value **Available**; it does not invent a completed run, receipt or result pin. The exact selected asset/version is preserved in Result and Using. Missing values, mismatched host identities and navigation-only workspace ports remain unavailable. `ProjectFlowNativeObservation` describes this read-only origin; normal output/source paging retains its identity. Native production-workspace connections also use the exact installed host manifest and declared port handles; a newer catalog release cannot redefine an older pin. Original standalone nodes without placement/version metadata retain their historical 1.0.0 contract. Unknown, mismatched and non-host pins cannot impersonate a production workspace.
+
+Whole-project Script retains its original narration source. Transcript uses the selected Voiceover take’s recorded transcript and word timings, independently of the editable narration draft. Older takes without stored transcript text derive it from their own timed words. A new Transcript-only run protects the original Voiceover document; changing an unrelated narration draft does not invalidate it. Original legacy receipts that also include Script remain valid with their stricter source checks. An older proposal cannot replace original reads with current documents, and a legacy result lacking derived proof must be rerun before guarded adoption. Other derived fields and arbitrary dynamic reads require separate attribution. Scoped narration and supported shot/scene collections capture their original Blueprint, Shot Plan, Animation, Panels and Board contributors, including empty originals whose later additions could change the result. They do not substitute the whole-project Script. Native asset inventories, generation records, scoped version histories and character/location/style collections can now retain their original contributor and membership proof when canonical reconstruction exactly matches the consumed value. A bounded v2 Canvas projection excludes only the exact host-dispatched producing placements while retaining their IDs/types, so saving their own output does not invalidate native collection membership. Current saved executable asset/generation members can retain their original selected-output, state and native-source evidence when exact canonical reconstruction matches the consumed collection. A producing placement’s own consumed previous output is captured separately when provable. Ambiguous, legacy, archived, private or unsupported collection members, local-only media, whole-project version metadata and noncanonical source documents remain unproven. v1 source reads stay compatible; new v2 captures require explicit server support. Media-dependent narration and arbitrary dynamic reads still require separate attribution.
+
+Stateful host runs retain the exact starting-memory identity and resulting-state digest alongside original input/output evidence. Original native reads carry through subsequent memory transitions, connected batches, loops and checkpoint recovery. Declared initial/reset memory is distinct from legacy saved memory even when its bytes match; old receipts cannot gain proof from current documents or by removing a warning. Missing or changed state proof blocks protected workspace adoption. This is host-maintained provenance, not cryptographic attestation against rewriting an entire saved receipt. Older retained plans/checkpoints may require their existing recovery/reset path when the new memory evidence changes the plan identity.
+
+Task-authored final Canvas adoption can bind the original native read union to the same transaction as the current task and Canvas execution checks. The host's `taskSourceReadSet` is retained in the exact save/recovery receipt, with explicit `assistantSourceReadSetVersions` capability negotiation. A lost response is recovered by reading the original commit; it does not resubmit an old proposal over newer work. Stale completed results may still be retained for review. Manual selection in saved Canvas projects now uses an acknowledged source save with the original native read union and `sourceCanvasPrecondition`, negotiated with `sourceCanvasPreconditionVersion:1`. Source roots and current execution content are checked under the same ordered transaction locks; layout-only changes are preserved. Exact request recovery distinguishes applied, not-applied and unresolved saves, including no-op selection, without replaying old work over newer selections. Servers without the capability refuse selection. Local drafts and unused-result retention remain separate. Legacy results do not gain missing original-source proof. Remaining native/background producers require separate coverage.
+
+The saved-project inspector and compact handoff can open the exact source Block workspace through existing draft-save navigation guards. Account, project, read access, placement and matching package source are checked after drafts finish saving. The existing Editor opening suppresses automatic narration import/export for this navigation request. Previews without workspace navigation say **Inspect source Block**. Compact handoffs show required inputs needing attention even when the primary value is ready; **Using** targets the first such input.
+
+Large Flow connection lists page 40 placements and offer **Find a Block** with direct keyboard access. Exact input links remain available after search. The map keeps its own bounded pages and selected neighborhood. Unchanged bounded scalar activity reports reuse the shared projection; new captured evidence, source changes and revoked access invalidate the relevant view.
+
+
+External controllers can review one complete retained local connected run with `preview_project_flow_completed_results`, then select it using `use_project_flow_completed_results`. Apply requires the exact returned Flow, Canvas and candidate digests, a new request ID and the current task fence. Every selected row must have its original sealed v2 source receipt. The server validates the existing plan and original source roots, rechecks project/connection/task authority, and saves through shared Canvas operations. An acknowledged retry returns its original receipt without selecting the result again, even if the current selection has changed.
+
+This external path supports complete recipe/JavaScript connected runs with current inputs, asset-descriptor batches with non-media outputs, and shared complete local loop receipts. All-assets, scene and selected-shots batches require the original complete inventory receipt captured and acknowledged before dispatch; it binds the original scope, ordered targets, exact plan and eight contributing workspace roots. Preview and apply check those original roots again, including workspaces that were empty when the batch started. JavaScript memory transitions require exact initial, reset or retained starting identity and resulting state with original sealed proof. Preview exposes digest-only `stateChanges`; apply saves the original outputs and memory without executing them again. Legacy/unproven or changed memory is unavailable. Hosted execution, decoded/generated media, incomplete runs and failure-recovery results still use their existing workspace review. Broad batches without original inventory proof remain unavailable; current inventory cannot be substituted for missing historical evidence. Inventory membership and each consumed item’s output or memory lineage are separate requirements. A local preview does not establish shared source proof. Preview and apply never dispatch a Block, load media, request model analysis or spend credits. A source/authority conflict keeps the retained result available for review; it does not silently rerun the workflow.
+
+Completed local loops can retain their exact whole receipt in shared Canvas history without selecting outputs or advancing memory. A failed shared save preserves the original device checkpoint. Shared `retainedLoopRuns` summaries expose bounded run identities, pass counts and current selection for review; they do not claim revalidation. Retention is limited to four envelopes, 512 KiB per envelope and 1 MiB total per starting placement; exceeding a bound keeps device recovery and reports the limit rather than evicting old history. External selection validates the original whole loop and every consecutive pass against current sources, memory, task and authority, then uses the existing adoption path without dispatch. In the native workspace, another editor can explicitly choose a shared run without its original device checkpoint. Review validates the original complete receipt; Use rechecks its shared identity and the reviewed Canvas execution state before acknowledged selection. A newer selection or changed source requires fresh review.
+
+Shared loop pass inspection uses the existing `list_project_flow_retained_results` and `inspect_project_flow_retained_result` operations. Initial discovery exposes bounded historical identities; explicit inspection verifies the original whole envelope before returning captured input identities and paged output/text/collection previews. It validates original evidence without requiring today's inputs to match, and does not select or execute the pass. Changed original history or revoked read access invalidates the response. Native Result review uses the same verified reader through **Inspect saved pass**.
+
+Existing-media and host-action selections carry explicit selection metadata. Flow separates them from worker execution receipts and attempt history; a media selection identity is not a run ID. Saved selection still checks current authority and the reviewed Canvas/source state.
+
+External connections must explicitly opt into `projects:write` alongside `projects:read` for reviewed Flow input, pin, result/memory changes and saved-media restoration. Defaults and existing connections do not gain permissions. Shared Flow reads recheck current connection authority after asynchronous work; all four Flow mutations recheck it in their write transaction, including replay. Media restoration rechecks through its existing before-write guard. Revocation, expiry, project/scope changes and suspension invalidate stale authority.
+
+### Completed background results
+
+In a saved Block workspace, open **Background results** beneath the result area to review already completed jobs. Editors can explicitly select a result whose original input, output and memory proof remains valid for the current project; viewers can inspect it. Selection rechecks the exact job, project, Block version, sources and shared Canvas and does not execute the Block or advance saved memory. Legacy jobs, pending validation journals and results with missing original source proof remain preview-only. Current source documents never replace missing original evidence. Connected fallback/bypass and unsupported derived sources may therefore remain unavailable for selection.
+
+Use the **+** between project placements to add a Block. **Edit workflow** in
+that dialog opens the ordered builder for adding, removing, disabling,
+duplicating, replacing, reordering and configuring placements. Changes remain a
+draft until **Save workflow**. A changed source requires a new Block version;
+the same ID/version cannot silently acquire different code.
+
+Removed, disabled, replaced or changed placements retain their SDK package
+(or built-in host contract), settings, prior results and connections in
+**Workflow history**. The old placement
+is inactive; it is not run by autosave or future-media automation. Re-enabling
+the same placement and source can recover its results for review, marked stale
+until rerun. Changing a producer or its inputs also marks affected downstream
+results stale. Each history entry offers **Download Block + SDK**. SDK packages
+come from that retained instance; built-in downloads follow the current-client
+source behavior described above.
+Scoped SDK `versions` context includes retained media as inactive previous
+versions; archived results do not become current assets or new generations.
+
+The full definition and selected stage travel with project/session saves. A newer
+installed type cannot replace an existing project's pinned definition.
+Use `node packages/block-cli/cli.js create-type my-type.json`, then `test`, `preview`,
+and `pack` on that JSON file. `preview` rehearses connected sandbox Blocks using
+fixture inputs and actual upstream outputs. It marks hosted workspaces as requiring
+a real project and never calls paid providers. `examples/text-workflow.stillmade.json` is a complete example.
+The broader editor command/workspace SDK is not yet exposed to external recipes.
+Do not invent `ctx.editor`, `ctx.sql`, `ctx.shell`, `ctx.fs` or `ctx.capabilities`
+methods; none exists in 0.1. Keep unsupported requirements explicit.

package/docs/project-types/testing.md

@@ -0,0 +1,72 @@
+# Rehearse connected workflows
+
+```sh
+node packages/block-cli/cli.js preview my-type.json
+node packages/block-cli/cli.js preview my-type.json sample-inputs.json
+```
+
+`sample-inputs.json` is keyed by Step ID, then input name:
+
+```json
+{ "first": { "text": "  My sample  " } }
+```
+
+`previewProjectType(type, options)` from `packages/block-platform/type-preview.js`
+rehearses the pinned workflow without changing it. Options accept `inputs`, scoped
+`context`, an abort `signal`, `onResult`, and a sandbox `run` implementation for
+browser workers. The CLI uses the same isolated Node runtime as Block tests.
+Unconnected inputs start with the Block's first fixture, then Step config and
+custom sample values; connected values always come from actual upstream output.
+Conditions use the production bypass rules. Inputs and outputs are validated at
+each boundary. Offline checks share a 15-second deadline and 4 MB combined
+sample budget. Interactive browser previews permit 64 MB of recorded data;
+waiting for hosted consent and execution does not consume the local deadline.
+
+The report contains a digest and per-Step results. `passed` means no executed
+Step failed; **only `complete: true` means all enabled Steps completed**. Hosted
+workspaces, missing context and dependent blocked Steps produce an incomplete
+report. The same connected rehearsal also runs within type fixture validation and server
+import admission; an executed combination that fails is rejected. Incomplete host
+coverage is marked explicitly. This does not replace static admission checks,
+individual fixtures, or actual host/media testing in a project. In the builder choose **Preview connected workflow**
+to inspect per-Step inputs, outputs and failures.
+
+
+### Interactive hosted rehearsal
+
+In the Project Type Builder, choose **Preview connected workflow**. For included
+hosted Blocks, complete or reuse each account-bound package review first. The
+preview then asks for a model, payment choice, and cost confirmation for each
+actual hosted invocation. A package review never substitutes its sample output
+for an upstream result. Cancel at any point to stop downstream execution.
+
+Use **Custom sample inputs** for values keyed by Step ID. Use **Sample project
+context** for a JSON object containing the context fields requested by Blocks:
+
+```json
+{"metadata":{"schemaVersion":1,"hasDialogue":true}}
+```
+
+Each Block receives only its declared context inputs and permissions. Context
+samples are copied; testing cannot write through to a production project.
+Conditions read the resolved inputs and apply the same pass-through rules used
+in production. Changing either sample clears the displayed prior result.
+
+Before passing hosted output downstream, StillMade re-fetches the authenticated
+run and checks the package, input, model selection, quote, output and media
+receipts. Generated image references can feed recipe image inputs: the browser
+decodes the verified media without resizing it. The recipe limit remains one
+megapixel. Arbitrary URLs in sample JSON do not authorize image decoding. Local
+JavaScript Blocks retain reference-based image contracts.
+
+The browser host opts into `interactive: true`, supplies `verifyHostedResult`,
+and may supply `resolveInput` for authorized media conversion. These are trusted
+host callbacks, never functions supplied by imported packages. Omitting the
+verifier prevents hosted execution. Keep interactive mode off in automated
+admission and CLI checks; enabling it does not provide provider credentials,
+payment authorization, or a server-certified workflow receipt.
+
+A successful sample rehearsal proves that those enabled Steps ran with those
+inputs. It does not prove every possible project, workspace interaction, or
+conditional branch. Manual StillMade workspaces still need their working preview
+or a real project. Changing accounts cancels the active hosted preview.