The per-topic proposals (T02-T18) with their source evidence and the alternatives that were rejected, plus the per-app work packages, so reviewers can see why each choice was made.
113 KiB
Topic proposals
Status: working record for review, 2026-11-10. These are the proposals from each design topic (T02–T18), in the order they were discussed, with the source evidence and the alternatives that were rejected. Later sections and their "outcome" notes amend earlier ones, so where they differ the later text wins, and ARCHITECTURE.md is the consolidated result. Each choice is in DESIGN-DECISIONS.md.
Code references name an app repository, a commit and a path (for example EffectCraft ce9eaec crates/render/src/pipeline.rs:622-632). They were read from local copies at those commits; upstream code has moved since. References to the earlier research notes, which are not in this repository, are kept as plain names.
SDK layers
These are cohesive responsibilities. They do not prescribe one crate, repository or service for every row.
| Layer | Primary user | Owns | Must not absorb |
|---|---|---|---|
| Guest SDK common module | Plugin author | Typed lifecycle/results/errors, parameter/state support, host-created handles, generated call wrappers, progress/cancellation and logging helpers | Installer, signing keys, user grants, private app Rust types or ambient filesystem/network authority |
| Generated app/family contracts | Plugin author | Supported operation types, data semantics, capability requirements and compatible versions exported by the app registry/ABI profile | A second hand-maintained interface definition or unsupported internal operations |
| Host adapter support | App maintainer | Registry inventory export, principal/scope enforcement hooks, module/profile admission, contribution registration and transaction/job/artifact integration | A common document engine or permission bypass for trusted-looking packages |
| Author tooling | Plugin author and reviewer | Create/add/inspect/check/test/dev/pack/prepare-release, pinned contract inventories, deterministic inventory/digests, dependency/licence report and compatibility differences | Automatic permission insertion, publication without a release action, user-side compilation during install |
| Conformance support | Author, app maintainer and reviewer | Real adapter fixtures, denied calls, output/state/cancel/migration cases, literal expected results or justified numerical tolerances | Mock-only proof that the actual app/backend is safe or correct |
| Management client/core/store | App/launcher maintainer and end user | Identity, verified package lifecycle, catalogue fetch/authentication, app setup/grants, resolution and retained releases/resources | Algorithm SDK functions or app-specific editing/rendering semantics |
One author workspace declares its package and adds app contributions. Most authors should use generated types and normal app controls rather than understand store schemas or cryptography. App maintainers implement their own contracts using reusable support. Release tooling generates routine metadata from authoritative declarations and exact bytes.
The Rust operation registry/inventory is the recommended source of truth. Existing effect/filter ABIs also need authoritative typed descriptions; not every pixel operation is a generic command. A future WIT/component encoding is generated only when justified and verified. Avoid a second schema authority and avoid serializing large image/audio data through an unsuitable generic request payload.
Family contracts
| Family | Normal contribution | SDK semantics required | Risks and special cases |
|---|---|---|---|
| A: transactional editing | Query selection, create/modify native objects, validate/preflight | Typed queries, durable/revision-checked handles, validated edit proposals, transaction and undo boundaries | Nested/queued rights, stale jobs, partial failure, side effects that undo cannot retract |
| B: raster/develop/material | Image filter/generator, brush/material/bake or develop operation | Colour/model/alpha/precision, bounds/bands/overlap/scale, selection and channel data, output validation | Seam equivalence, non-finite output, memory copies, input/resource retention and host-owned model readiness |
| C: temporal composition/video | Effect, transition, frame processing | Timebase/frame dependencies, keyframed parameters, seek/reset, independent instance and render-session state | Backward/random evaluation, concurrent preview/export, missing inputs, GPU/device failure |
| D: geometry/modeling | Object filter, live appearance, parametric feature | Units, object/topology schema, bounds/validation, evaluation dependencies, rebuild/state/fallback | Invalid geometry, solver cost, stale models, live-feature cache invalidation |
| E: text/page/layout | Text/story/page edit, layout/prepress validator | Durable positions/ranges, stories/styles, pages/frames/spreads, layout/reflow and output | Offset invalidation, reflow effects, document-wide work, PDF-specific object lifetimes |
| F: calculation | Custom workbook function or typed range operation | Cell types, dependency/recalculation graph, deterministic inputs/results, cycle/error contract | Recursive/cyclic work, cached dependencies, external-data permission, synchronous evaluator deadlines |
| G: real-time audio | DSP effect/instrument, MIDI/event processor | Prepare/process/reset, rate/layout/blocks, sample offsets, transport, automation, latency/tail, state and editor lifecycle | Callback allocation/locking/deadlines, worker failure, device change, offline bounce versus live processing |
| H: provider/workflow jobs | Local model/provider or explicit external workflow | Declared inputs/outputs, model/node readiness, progress/cancel, durable jobs, egress and credential brokers | Remote-only availability, data disclosure, external code/process execution, restarts and partial uploads |
| I: data/theme/resource | Theme, LUT, preset, brush set, template, localization | Typed importer and version, bounded parsing, identity/licence/readiness, semantic theme mapping | Hostile data, active choice versus install, missing models, no install-time execution |
Panels/tools/widgets, settings/keymaps/context menus, format handlers and artifacts cross these families. They use versioned registration and lifecycle contracts. They do not imply arbitrary UI code, replacement of builtin handlers or new global command authority.
All sixteen apps
Membership and candidate contributions are design requirements. The evidence column identifies what has actually been established and where to read it; full source notes carry revisions and limitations.
| App | Families | App-specific SDK requirements | Existing foundation and investigation |
|---|---|---|---|
| EffectCraft | A, B, C | Layers/compositions, effect/keyframe parameters, premultiplied pixel/time context, frame dependencies and persistent render references | WASM/helper/effect systems and GitHub Library source; CLI/output/lifetime gaps in media audit |
| PhotoCraft | A, B, I | Layers/masks/selection, colour models and alpha, band overlap, destructive/smart filters, resource/theme mapping | WASM filter ABI and separate theme branch; smart/CLI/identity gaps in media audit |
| FilmCraft | A, C, G, I | Timeline/clips/tracks, media/frame/audio time, transitions, export jobs and timeline appearance | Command/job foundation; processing plugin host not established in media audit |
| LightCraft | A, B, I | Catalog items, metadata/develop recipes, RAW stage placement, scoped batch/export and presets | Existing commands/resource importers; no code host established in media audit |
| ArtCraft | H, I | Provider/model/media jobs, explicit egress, model/workflow readiness, credential and result-ingestion boundaries | Native provider/job architecture differs from editor registries in media audit |
| FigCraft | A, D, E | Node/layout/selection edits, transactions, panels/tools/widgets and host-written artifacts | Existing WASM commands/panels with actual policy; integrity/control/output gaps in design audit |
| VectorCraft | A, D, E, I | Object/units schemas, live appearances, precise export/format selection and persistent resources | Filter/live-effect/exporter ABI and CLI store attachment in design audit |
| PDFCraft | A, E | Page/object queries and edits, forms/annotations where supported, history/preflight and PDF writes | Facade/automation foundation, incomplete plugin/UI tracing in design audit |
| DesignCraft | A, E, I | Stories/styles/frames/spreads, units, pointer tools, reflow/prepress/export | Existing commands and journaled tools; plugin seams needed in design audit |
| DeckCraft | A, E, C, I | Slides/shapes/text, transitions, presentation subscriptions and export artifacts | Commands/CLI, separate playback lifecycle not established as plugin contract in design audit |
| SoundCraft | A, G, I | Routing, DSP/instruments, audio automation/MIDI/state, presets and editors | Existing native-format hosts do not prove confinement in domain audit |
| CADCraft | A, D, I | Entities/units, explicit headless parameters versus prompts, constraints where supported, patterns/resources | Commands and AutoLISP with separate trust concerns in domain audit |
| SolidCraft | A, D, I | Feature graph/rebuild/model state, geometry/solver boundaries and missing-feature fallback | Manifest/design foundation, executable host not established in domain audit |
| TextureCraft | A, B, D, I | Mesh/UV/texture-set/channel scopes, strokes/materials/bake/composite and resource ownership | Sessions/commands, job and resource lifetime work in domain audit |
| WordCraft | A, E, I | Durable text ranges/styles/stories, layout/validation and output | Commands/history, internal duplicate policy and untraced boundaries in domain audit |
| GridCraft | A, F, I | Typed ranges/cells, workbook queries/edits, function/recalc and macro policy boundaries | Command/calc/macro foundations; custom function contract and test-helper qualifications in domain audit |
Family C membership for presentation transitions does not equate DeckCraft to a video compositor. Family G membership for timeline audio does not make FilmCraft a real-time plugin host. The contract lists what must be discussed; an adapter advertises only implemented capabilities.
What belongs in common libraries
Share identity, version/policy vocabulary, descriptors/inventory tooling, principal/handle mechanics, job/error/artifact envelopes, parameter/declarative UI descriptions and conformance infrastructure where actual consumers agree. Reuse craft-ext-core/store for package management, existing craft-ui drawing support and craft-keymap conflict handling. Inspect definitions before choosing concrete calls.
Keep actual operations, document models, transaction application, file format serialization, colour/geometry/time/audio conversion, render scheduling and theme token mapping in apps. Algorithm crates can be reused by an author across contributions without making their app ABIs identical.
First structure the coherent modules, then choose crate boundaries. A logical SDK split is not a mandate for one dependency per feature. A new craft-libs crate needs real multiple-app use and no dependency on application crates. No relocation of craft-extensions or new common framework is approved merely by listing these responsibilities.
Questions to resolve in the session
For one concrete contribution, name what the author implements, what the SDK generates, what the app supplies, and which authority the host enforces. Follow it through data conversion, editing/evaluation, save/reopen, headless invocation and failure. Then test whether a second app shares actual semantics or only the name. This determines useful sharing more reliably than grouping apps by marketing category.
T02 session proposal: contract layers and interaction styles
Status: second revision in the design session, 2026-11-08, after an end-to-end review from every actor's perspective. Not accepted. It replaces the first "two planes" proposal, which misclassified VectorCraft object filters and GridCraft functions. It applies the accepted functional default "standardize purpose-specific interfaces where real app requirements agree" and the T01 grant decision.
Two independent axes
A contribution has a domain (what data it understands) and an interaction style (how it runs). The first proposal fused them.
| Style | How it runs | Imports | Typical contributions | Today's evidence |
|---|---|---|---|---|
| Transform | Host hands a scoped, typed input; plugin returns a typed output; host validates and commits | None beyond its contract; cannot reach documents, files or network | Raster filter, temporal effect, audio processor, object filter, live appearance, parametric feature, workbook function, exporter encoding | PhotoCraft pc_filter and VectorCraft ABI 1 already have no host imports; VectorCraft applies output in one s.edit and refuses foreign object IDs |
| Session | Plugin calls the app's generated operations under grants, inside host-owned transactions | Generated app operations, each checked against the grant and scope | Commands, panels, pointer tools, canvas widgets, validators that propose fixes | FigCraft sandbox ABI 4 with 14 host imports and real command/read restrictions |
| Data | No code. A typed importer reads it | None | Themes, LUTs, presets, templates, localization | LightCraft resource importers; SoundCraft track presets; PhotoCraft theme branch |
Effective authority of a runtime instance is its style's imports ∩ the package's grant in that app. A transform module therefore cannot use a network grant that a session contribution in the same package received. This keeps the T01 single grant sheet while staying narrow by construction.
Three contract layers
| Layer | Contents | Owner | Shared? |
|---|---|---|---|
| 1. Common mechanics | Identity, parameters with units/ranges/animation flags, declarative UI, results and stable error codes, jobs/progress/cancel, handles and revisions, edit-proposal envelope, bounded logs | Shared crates (T03 decides placement) | All apps |
| 2. Shared domain contracts | raster (image regions, pixel formats, regions of interest), temporal (time context, frame access, instance state), audio (prepare/process/reset, blocks, events, latency/tail), typed resource formats such as LUTs. Candidate only: path2d |
One shared definition per domain, each with one conformance suite | Only apps whose adapters pass that suite |
| 3. App contracts | Document operations and app-specific extensions (effectcraft.*, figcraft.*, gridcraft.*), generated from the app's Rust registry |
The app | No |
Shared domain contracts are designed now where the domain is known to span apps: raster (PhotoCraft, EffectCraft, LightCraft, TextureCraft, FilmCraft), temporal (EffectCraft, FilmCraft, DeckCraft transitions), audio (SoundCraft real-time, FilmCraft offline). An app makes a contract available only after its adapter passes the suite. An unforeseen need starts as an app extension and is promoted when a second app needs the same meaning.
Domain contract shape
Core plus named optional extensions, following OpenFX (host/plugin describe depths, components, premultiplication, tiling, temporal access and regions of interest) and CLAP (small core, negotiated extensions; also the audio model SoundCraft already hosts).
- The plugin declares supported pixel/colour models, accepted alpha/transfer formats, required extensions and optional ones it can use.
- The app advertises contract versions and extensions it implements, plus limits such as maximum region.
- Compatibility per contribution per app is computed at catalogue display, install, enable and load from the same function: available, or unavailable with a reason.
- Optional features are queried at runtime from a host-provided feature set; a plugin must behave correctly without them.
Host obligations (every app adapter)
- Convert native data to a format the plugin accepted, using shared fixture-tested conversion helpers; never silently convert colour models (CMYK, Lab).
- Supply the requested input region, fall back to whole-image when within the workload profile, or refuse before work starts. Never produce seams silently.
- Evaluate keyframes and convert spatial units to render pixels; the plugin receives plain values plus render scale.
- Validate output dimensions, finiteness and object IDs; a failure is a terminal failure, never a pass-through success. A labelled preview fallback is allowed.
- Commit through the app's own transaction/undo; save live features with exact release references (T01).
- Isolate instances: stateless transforms may be pooled and parallelized; stateful ones get one instance per feature instance per render session, with reset on seek.
Plugin obligations (checked by SDK tests and review)
- Deterministic output for the same input, parameters and context; no relaxed SIMD or other nondeterministic features in transform modules.
- Tile invariance: whole-image and tiled output agree (exactly, or within a declared numerical tolerance). The conformance suite checks this; it exposes an under-declared region.
- Honest declarations: unsupported formats are declared, not mishandled.
Cross-app result consistency
Promise: the same contract input, parameters and context give the same output in every app. Not promised: identical appearance across apps, because each app's colour pipeline, working space and compositing are app-owned. Plugins needing a particular working space declare it and the host converts or refuses.
Evolution and governance
- Each domain contract has named maintainers drawn from implementing apps; a change requires their review and an updated conformance suite.
- Minor versions add optional items only. A major version is a new contract an app can implement alongside the old one.
- Apps advertise exact contract versions; the SDK targets a minimum version; the catalogue shows per-app compatibility from those records.
- Existing ABIs remain legacy app profiles behind adapters (
effectcraft.wasm-effect@1,photocraft.wasm-filter@1,vectorcraft.wasm@1,figcraft.sandbox@4). No automatic conversion of old modules.
Known exclusions and dependencies
- SoundCraft's existing in-process CLAP/VST3/AU hosting is native third-party code outside the sandbox promise. It stays a separate, explicitly labelled mechanism until T06 decides a confined backend; the Craft audio contract does not inherit its trust.
- CADCraft AutoLISP is an unconfined existing surface; no package code runs there before T06 confinement.
- GPU, interpreter performance and backend choice are T06/T16. Saved-feature missing/repair behaviour is T13. Generated layout of crates and SDK is T03; operation signatures are T04.
Worked example
Ink & Grain ships one raster.filter@1 transform module referenced by EffectCraft and PhotoCraft contributions, and one FigCraft session module for "Halftone fill", both built from a shared dot_layout crate. A later VectorCraft "halftone pattern" object filter would be a transform against VectorCraft's object contract (or path2d if promoted), not the raster module.
T03 session proposal: SDK, toolchain and author experience
Status: proposed in the design session, 2026-11-08, after an end-to-end review from author, reviewer, app developer, contract maintainer, end user and CLI perspectives. Not accepted. Builds on the T01 grant decision and the accepted T02 contract structure. No SDK exists today; craft-extensions has core/store only (Jeremy's d7: standalone contract/store workspace).
Placement: one plugin-platform workspace
Keep every plugin-platform crate in craft-extensions: core, store, contract inventories, generator, guest SDK, host support, conformance and author CLI. One repository gives atomic changes across manifest, validator, guest and host, one version line and one CI. This follows the existing decision to reuse craft-extensions and Jeremy's d7. It corrects the earlier T02 hint that domain contracts might live in craft-libs. App-specific glue stays in each app repository.
| Crate (names illustrative) | Used by | Contents |
|---|---|---|
craft-ext-core (exists) |
Everyone | Manifest, identity, compatibility, the one validator used by SDK, catalogue bot and installer |
craft-ext-store (exists) |
Apps, launcher, craft-ext dev |
Installed releases, setup, grants, readers |
craft-ext-contracts |
Generator, host, SDK | Hand-written Rust definitions of shared domain contracts plus checked-in generated inventories of app contracts, all in one language-neutral inventory format |
craft-guest |
Authors | Common mechanics: parameters derive, results/errors, progress/cancel, logging, entry-point macros, custom-section emission |
craft-guest-<contract> |
Authors | Generated typed bindings, one crate per domain or app contract (craft-guest-raster, craft-guest-figcraft). Crate major = contract major |
craft-ext-host |
App developers | Engine admission profile, module loading, linker built from descriptors, invocation context and principal, shared conversion helpers, adapter traits per domain contract |
craft-ext-conformance |
App developers, authors, reviewers | Domain-contract suites as a library that apps run in their own cargo test; reference host for transforms |
craft-ext (CLI) |
Authors, reviewers | create, add, inspect, build, check, test, dev, pack, prepare-release, and verify for reviewers |
Contract pipeline (single source, generated consumers)
- App contracts: the app's Rust registry marks deliberately exposed operations with descriptor metadata. An app
xtask export-contractwrites<app>/<contract>@<version>.json. - App CI diffs the export against the last published version: removed or changed operations without a major bump fail, the same approach as
cargo-semver-checksand protobufbuf breaking. CI work goes through craft-common-actions under house rule 11. - A reviewed PR copies the inventory into craft-extensions. The generator emits the guest crate and reference docs. Generated code is committed and CI fails if regeneration differs (rust-analyzer/AWS SDK codegen practice).
- Domain contracts are hand-written Rust in
craft-ext-contractsand export the same inventory format, so tooling treats them identically. - Guest crates are versioned so Cargo's semver resolution gives authors compatible minors automatically;
Cargo.lockpins the exact inventory used, andpackrecords inventory digests in the manifest.
Publishing guest crates to crates.io (giving docs.rs reference docs) is the recommended distribution, but it is a publication decision for the user and maintainers, not authorized here. Git tags on craft-extensions are the interim alternative.
Author declarations: code for behaviour, one file for authority
Craft.tomlat the workspace root holds only facts a reviewer must read as a whole: package UUID, display name, version, licence, publisher claim, links, and permissions per app (matching the T01 grant unit).- Contributions and parameters live in code:
#[craft::transform(contract = "raster.filter@1", id = "halftone", apps = ["photocraft", "effectcraft"])]on a type, and#[derive(craft::Params)]on its parameter struct (units, ranges, animatable, labels, localization keys). The macros write descriptors into a WebAssembly custom section;craft-ext packreads it from the compiled module, so manifest and code cannot drift. PhotoCraft'spc_manifestexport is precedent for module-carried metadata. - Permissions are never inserted automatically (accepted).
checkcomputes required capabilities from the module's actual imports and the inventory, fails when one is undeclared, warns when one is unused, and prints the exact line to add.
Author toolchain
- Rust first,
wasm32-unknown-unknown, toolchain pinned byrust-toolchain.tomlin the template. The template's.cargo/config.tomlsets the target features the apps' wasmi engine profile accepts;checkvalidates used features and imports against each target app's engine profile. Recent Rust enables some WebAssembly proposals by default on this target, so this must be verified against the actual wasmi versions before the template is fixed. - Deterministic builds: path remapping, locked dependencies, normalized zip ordering/timestamps/permissions. A reviewer can rebuild from a source tag and compare digests (optional evidence, not a review substitute).
- Supply chain:
cargo-denyfor licences and advisories, a dependency inventory/SBOM produced bypack, licence policy from T17. - Other languages later, only with generated and verified bindings; the inventory format is language-neutral.
Testing at three levels
| Level | Runs | Proves |
|---|---|---|
| Unit | Native cargo test of algorithm crates |
Algorithm behaviour, fast |
| Contract | craft-ext test: module in craft-ext-host with the same engine configuration as apps; domain conformance (determinism, tile invariance, declared formats, parameter ranges, cancellation) and literal fixtures with snapshot comparison |
The compiled module meets the shared contract without any app installed |
| App | The app's headless CLI loads the packed package against fixtures (<app>-cli plugin test), like VS Code extension tests running in a real VS Code |
Session contributions and the actual adapter; final acceptance |
Apps without a headless plugin test entry cannot offer session contracts to authors; that becomes part of each app's adapter obligation.
Development loop
craft-ext dev --app photocraft builds, packs, installs into a separate labelled development store, starts or attaches to the app pointed at that store, streams plugin logs and reloads on change. Transforms swap between invocations; session contributions dispose UI and instances first. Development grants are isolated from the user store. Release app builds treat development packages as local installs with all normal checks.
Release and submission
craft-ext prepare-release builds deterministically, runs check and test, writes the zip, inventory/SBOM, and the catalogue record releases/<version>.toml, and compares with the previous release: removed or renamed contribution IDs, parameter/state schema changes without migration, and widened permissions are reported prominently. A template GitHub Actions workflow for authors builds on a tag, uploads the asset and adds GitHub artifact attestations. Submission is an explicit author PR; the tool never publishes on its own.
Trust boundary
The SDK is a convenience, never a trust anchor. A hand-made package gets the same validation from craft-ext-core, the same import checks at load and the same grants. The catalogue bot, check and the installer call the same validator.
T04 session proposal: one operation path for GUI, CLI, automation and plugins
Status: proposed in the design session, 2026-11-08, after an end-to-end review. Not accepted. Builds on T01–T03.
Evidence that shapes it
- Every audited app has a static command table (
cmd!/query!/CommandSpec) with loosely typed parameters described by strings, and anexecute(id, params)with no caller identity (EffectCraftdispatch.rs:9; six domain apps listed in the domain audit F2). - Policy exists only at some entry points: FigCraft checks its denylist/allowlist inside the plugin host (
plugins.rs:148-181) while its control channel'sengine.executereachesexecute_asdirectly. PhotoCraft and TextureCraft have real headless filesystem modes andauthorize_*hooks. - Domain apps share a snapshot/label/rollback transaction pattern (domain audit F5); FigCraft and VectorCraft already make one plugin run one undo step.
- Several apps expose every command over MCP or a control channel; some channels have no authentication (EffectCraft, LightCraft, SoundCraft).
The structure
1. Extend each app's existing registry; do not add a second one. Each descriptor gains:
| Field | Meaning |
|---|---|
args, result |
Rust types with serde and schemars derives; JSON Schema generated from them feeds SDK, CLI help and MCP tool schemas |
kind |
Query (reads, no undo), Edit (one transaction), Job (asynchronous, progress/cancel, commits through an Edit), Effect (external side effect that undo cannot retract: file write, network, process) |
exposure |
Set of caller kinds allowed: Gui, Cli, Automation, Plugin. Plugin exposure is opt-in per operation; management operations (install, enable, grant, settings that change authority) are never plugin-exposed |
requires(resolved) -> CapabilitySet |
Maintainer-written function over resolved targets and arguments, unit-tested; covers parameter-dependent rights (S08) |
interaction |
None, Optional, Required; headless callers missing input get InputRequired listing what is missing |
contract, since, deprecated |
Version metadata for the exported inventory |
2. One dispatcher with a mandatory invocation context.
fn execute(&mut self, inv: &Invocation, op: OpId, args: Args) -> Result<Outcome, OpError>
Invocation {
principal: Principal, // User(Gui) | Cli(session) | Automation(client, scope)
// | Plugin(app, package, release, contribution, grant_generation)
origin: Vec<Principal>, // chain for nested/queued work; never upgraded
scope: CapturedScope, // document, revision, selection captured at start
deadline, cancel: CancelToken,
transaction: Option<TxnId>, // nested calls join the outer transaction
}
The old execute(id, params) signature is removed, so a new entry point that bypasses policy does not compile. Every caller (menus, keymap, panels, CLI, MCP, control channel, scripts such as GridCraft macros and CADCraft AutoLISP, plugin imports) builds an Invocation. Migration is mechanical: existing callers pass their real principal; all existing descriptors default to no plugin exposure.
3. One authorization function. authorize(inv, descriptor, resolved) -> Allow | Deny(reason) | NeedsConsent. Order: exposure for caller kind, then argument validation and resolution, then requires(resolved) against the principal's effective authority (T02: style imports intersected with package grant), then scope (targets must lie inside the captured scope). NeedsConsent only returns to interactive user callers; plugins and headless callers get Deny with a reason. All denials happen before any side effect.
4. Handles instead of paths and pointers. Plugins receive opaque, revision-carrying handles for nodes, layers, ranges and jobs, and artifact roles for outputs; the host chooses and writes destinations. User-chosen inputs arrive as host-issued file tokens, like browser File System Access handles, macOS security-scoped bookmarks and WASI preopens. A stale handle yields StaleDocument.
5. Transactions owned by the dispatcher. An Edit opens a transaction (existing snapshot/rollback), runs, validates, commits one labelled undo step showing origin ("Halftone fill · Ink & Grain"), and rolls back on error, trap, cancel or budget exhaustion. Calls nested inside a plugin invocation join it, so one plugin command is one undo step. Plugins cannot reach undo/redo or history operations.
6. Two execution shapes for session plugins.
- Short command: runs with an exclusive document transaction under a strict time/fuel budget.
- Long work: a
Jobreads from a captured revision, computes off the editing thread, then commits an edit proposal with an optimistic revision check. If the document changed, the app's operation decides: reject withStaleDocumentor apply where provably independent. No plugin callbacks run inside another transaction (no reentrancy).
7. Data paths. Control-plane arguments are JSON, validated against the schema with unknown fields rejected and size/depth limits. One encoding keeps CLI, MCP and plugin validation identical; generated wrappers hide it. Bulk image/audio/geometry data uses T02 handles and buffers, never serialized command payloads.
8. Generated surfaces. From the same inventory: SDK bindings (T03), CLI ops list --json, op <id> --args, generated help and existing commands kept as aliases, MCP tool schemas, reference docs. Stable error codes map to CLI exit codes and MCP errors.
9. Nested plugins and confused deputies. A plugin that applies another installed transform passes data only; the inner code runs under its own contract and grant. Authority never transfers between principals in either direction. Plugin-to-plugin APIs remain a future family.
Out of scope here
Authentication and scope of automation sessions (T15), consent UI and grant storage (T05), runtime budgets and traps (T06), job persistence and artifacts across restarts (T15/T16). Unauthenticated control channels are an existing issue that the dispatcher cannot fix; it only guarantees that an authenticated channel's principal is enforced.
T04 revision after the all-perspective review
Status: revision proposed 2026-11-09 after walking the flow as end user, plugin author, transform and session plugin, fresh CLI, attached CLI, MCP agent, in-app script, app maintainer, reviewer and support. Evidence from EffectCraft ce9eaec and FigCraft 0e86f359. Amends the T04 proposal above; not accepted.
New evidence
- Authority hides in generic commands. EffectCraft
prefs.setcan change the Scripting permissions;crates/automation/src/confine.rs:205-230special-cases it and batch$Nreferences by hand. Per-operation exposure alone would miss this. - UI enablement is used as a gate.
Session::execute(crates/engine/src/session/dispatch.rs:9) refuses a command whenspec.enabledfails, unless explicit targets are passed. Availability and authorization are mixed. - Commands feed other systems with no origin.
executeappends to a 10 000-entry journal and callslearn_observe(habit learning) for every caller. - FigCraft's control channel reaches
engine.executefor any command (crates/mcp/tests/it/attached.rs:129), outside the plugin host's checks.
Amendments
- Separate three questions the dispatcher answers, in order: Is this caller kind allowed this operation? (exposure), Is it permitted with these resolved arguments? (authorization), Does it make sense right now? (availability, the existing
enabled). Availability is a UI hint and an error message, never a security check, and explicit targets never skip authorization. - Authority-changing state is its own operations. Settings that change what callers may do (scripting permissions, grants, enablement, install, trusted folders, update sources) move out of generic
prefs.setintoManagementoperations. Generic setters reject those keys. Management operations are exposed toGuionly, plusCli/Automationwith a management scope (Q1). This removes the hand-written special cases inconfine.rs. - Side effects run after commit (outbox). Inside a transaction, an
Effect(file write, network, process launch) is queued, not performed. It runs only after the edit commits and is dropped on rollback. Results that undo cannot retract are reported separately ("Exported 3 files"). Standard transactional-outbox practice. - Origin travels everywhere the command goes. Journal entries, undo labels, habit learning, logs and events carry the
Principal. Plugin and automation calls do not train user habits. Replaying a journal or macro runs under the replayer's principal; plugin-originated entries are marked in the replay preview. - Batches are one invocation. A batch (EffectCraft
batch, MCP multi-step) is authorized step by step with the same principal and runs as one transaction;$Nreferences are resolved before authorization, so confinement does not need its own batch rules. - Events after commit, never inside. Plugins observing document changes receive a committed-change notification with the new revision, after the transaction. Prevents re-entrancy and loops; a plugin reacting with an edit makes a new invocation with itself as origin, and the origin chain is capped.
- Compatibility is checked at load, not mid-call. A session plugin's imported operations are resolved against the app's exported inventory when it loads. A missing or major-mismatched operation makes the contribution unavailable with a reason, instead of failing halfway through a user's edit.
- Hot paths stay fast. The
Guiprincipal has full user authority, so authorization is a constant-time check. Slider drags keep the existing merge-key undo folding. Per-call cost is bounded for plugins by the T06 budget. - Where the shared types live. Following T03 A, the
Invocation,Principal, descriptor, error and authorization scaffolding live in a small craft-extensions crate (illustrative namecraft-ext-ops) that apps depend on even without plugins. Operation definitions and data stay in apps. - Migration per app, in this order: add
Invocationand the newexecutesignature with every existing caller passing its real principal; give every descriptorkindand default exposure (Gui | Cli | Automation, noPlugin); split authority-changing settings into management operations; add schemas; then open selected operations to plugins. Each step is shippable on its own.
Alternatives rejected
| Alternative | Why not |
|---|---|
| Hand-written separate plugin API per app (FigCraft today) | Drifts from CLI/GUI behaviour and duplicates validation; the control channel already bypasses it |
| WebAssembly Component Model / WIT interface per operation | wasmi, the engine all apps use, does not run components; would also split validation from CLI/MCP |
| Pure object-capability passing for everything | Strongest model, but a rewrite of every app's command layer; handles and captured scope give most of the benefit |
| Policy only at each entry point (today) | Every new entry point must remember the checks; FigCraft and EffectCraft already show the gap |
T05 session proposal: permissions and consent
Status: proposed 2026-11-09 after an all-perspective review (end user, plugin author, transform and session plugin, reviewer, app maintainer, fresh CLI, attached agent, support). Builds on T01 (grant per package per app, enablement per contribution), T02 (style imports intersected with grant) and T04 (resolved-argument authorization, management operations). Not accepted.
Evidence
- craft-extensions
a6c5fae:Manifest.permissions: Vec<String>must be empty in version 1 (crates/ext-core/src/manifest.rs:93,174). No grant store exists. - FigCraft
0e86f359: manifestpermissions {access: read|write, commands: [...], saveFile}; install confirmation shows them; read-only and command allowlists are enforced, andsaveFileyields one host save dialog (crates/engine/src/plugins_tests.rs:132,458-467). - EffectCraft
ce9eaec: one global Application Scripting setting (file and network access, warning before executing files) that scripts cannot change (crates/engine/src/settings/prefs/sections.rs:55-66). - PhotoCraft
655295b2: per-commandauthorize_*checks for automation, render and smart sources (crates/automation/src/workspace.rs:327-398).
Each app invented its own vocabulary; none is shared, none scales to sixteen apps.
1. Vocabulary: a small fixed set of permission families with scopes
A permission is family + access + scope. Families are shared by every app; operations map onto them through requires(resolved) (T04), so the number of permissions stays small however many operations exist.
| Family | Access | Scopes | Plain sentence (host-written) |
|---|---|---|---|
| Document | read, edit | selection, current document, all open documents | "Read and change the selected layers" |
| Files | read, write | picked item (one-time), picked folder (remembered), own storage | "Save files where you choose" |
| Network | connect | listed https domains; never loopback, private ranges or the app's own channels | "Connect to api.example.com" |
| Account | use | one named provider, brokered by the host | "Use your Example account; it never sees your password" |
| Clipboard | read, write | on a user action only | "Read the clipboard when you paste" |
Free, never asked: computing on its inputs, returning results, progress and logs, bounded private storage, its own UI placement (that is enablement, T01).
Not grantable to WebAssembly plugins: processes, native code, raw sockets, other plugins' storage, management operations. Existing native helpers (EffectCraft helper-host) stay a separate legacy profile for T06.
App-specific needs (LightCraft catalogue collections, GridCraft external data) are new scopes of an existing family where possible; a genuinely new family needs a host-written sentence and is promoted to shared on a second consumer (same rule as T02).
2. Required and optional
- Required rights must be granted before the contribution can be enabled.
- Optional rights leave everything else working; a call without one returns
Denied(needs_permission), which the SDK forces authors to handle. - Picking is permission (powerbox): when the user picks a file or folder in a host dialog, that pick is the grant for that item. No separate prompt. Same as macOS powerbox, browser File System Access and Android's storage picker.
3. When the user is asked
| Moment | What happens |
|---|---|
| Setup in an app (T01) | One sheet: the union of required rights in plain sentences, optional rights as toggles, off by default. Combination warnings computed by the host (document read + network: "could send your document to api.example.com") |
| First use of an optional right | Only during a user-started action in the GUI: a host-drawn prompt naming the plugin and the exact scope. Never inside plugin-drawn UI |
| Update that widens rights | The new release stays staged; the old one keeps working until the user accepts (store mechanics in T08). Narrower or equal rights carry over silently under verified continuity |
| Headless, CLI run, agents, render queue | Never prompt. Missing right is an explicit failure with the exact grant to add |
Author-supplied purpose text is shown as a quoted, length-limited claim beneath the host's sentence, never instead of it.
4. Grant record and live enforcement
Grant {
app, package_uuid, source_binding, // T07 identity; continuity for updates
rights: Set<Permission>, // normalized family/access/scope
tokens: Set<PickedItemToken>, // remembered folders
generation: u64, // bumped on every change
granted_release_digest, granted_at,
}
Stored in craft-ext-store, one per (app, package). Every runtime instance holds the generation it started with; each host call compares it. Revocation therefore takes effect at the plugin's next host call; running edits roll back and jobs cancel. Queued jobs check the grant when they start, not when queued.
Grants live with the user on that machine, never in projects. Opening a project that uses a plugin needing rights asks in setup; a headless render with a missing right fails explicitly, never drops the effect.
5. Managing grants
- GUI: per-app plugin manager shows each package's rights, last use and a revoke per right. Disable keeps grants; uninstall deletes them.
- Fresh CLI (the user, T04 Q1):
<app>-cli plugin grant|revoke|permissions. Grants are management commands, separate from running work: no--allow-allon execution commands. - Attached agents: management scope approved in the app (T04 Q1).
- Local log of grant changes and denials (privacy in T16).
6. Effective authority (unchanged formula, now concrete)
style imports ∩ grant.rights ∩ host-supported ∩ invocation scope ∩ policy. Policy is an optional machine-wide plugin policy (for example "no network for plugins"), read-only to plugins and agents.
7. Migration of existing systems
| Today | Becomes |
|---|---|
FigCraft access: read/write |
Document read/edit on current document |
FigCraft commands: [...] |
Kept in its legacy app profile; new packages use plugin exposure plus families |
FigCraft saveFile |
Files write, picked item |
| EffectCraft Application Scripting | Scripts as their own principal with the same families; changing them is a management operation |
PhotoCraft authorize_* |
requires(resolved) on the descriptors |
craft-extensions permissions: Vec<String> (empty in v1) |
Version 2 manifest: per-app families and scopes |
Typical outcome
A transform such as a halftone or glow asks for nothing: setup says it cannot reach files, network or other documents. A FigCraft panel that edits the selection shows one sheet. A plugin that uploads renders shows one sheet with the account and domain, plus the combination warning.
Open-ecosystem direction (2026-11-09) and its effect on T01–T05
User direction: plugins may use the CLI and its tools; do not restrict what the community builds; plugins cannot change built-in features; plugins are free and open source; store plugins must be reviewed as safe and not malicious; store plugins are MIT or Apache-2.0.
Interpretation
- "Use the CLI and its tools" means a plugin can call every operation the app's CLI and MCP tools offer, in process, through the T04 dispatcher, with the plugin as principal. It does not mean launching
<app>-clias a process: a process runs native code with the user's full power, outside the sandbox, and could change built-in features and settings. Same capability, kept inside the checks. - "Cannot change main features" is the T01 protected core made concrete. Plugins can use built-ins and add new things; they cannot replace, remove, disable, re-bind or alter: built-in commands, tools, effects, menus and shortcuts; default settings and app preferences; built-in file-format handlers; undo/history; updates; plugin management and permissions. They edit documents, which is their purpose.
Changes to earlier topics
| Topic | Before | Now |
|---|---|---|
| T04 exposure | Plugin exposure opt-in per operation | Default on: an operation exposed to Cli or Automation is exposed to Plugin unless marked Management or Core (changes built-in behaviour) or Internal. App maintainers no longer gate the community operation by operation; they only mark the protected ones, and CI checks every operation has a classification |
| T05 | Families as user-facing permissions | Kept; the families now cover the whole CLI surface through requires(resolved), so permissions describe what data and where, not which features. Nothing the CLI can do on a document is unavailable to plugins; it is only disclosed and scoped |
| T02 | Session style calls selected app operations | Session style calls the full exposed operation surface |
| T09/T17 store | Licence list open; proprietary and restricted releases designed for | Store accepts only open-source plugins under MIT or Apache-2.0 (either or both), with a public source repository. Proprietary distribution is not a store goal |
Store admission: how "safe and not malicious" is checked
No review can prove absence of malice, so admission combines review with limits that hold even if review misses something.
- Open source required: public repository, licence file MIT and/or Apache-2.0, SPDX expression in
Craft.toml. - Reproducible build: the catalogue bot rebuilds the tagged commit with the pinned toolchain (T03 deterministic builds) and the digest must match the submitted asset. What reviewers read is exactly what users run. Was optional evidence in T03; now mandatory for the store.
- Automated checks (bot, every release):
craft-ext-corevalidator; WebAssembly import and feature scan against declared style and permissions;cargo-denylicences and advisories; dependency inventory; declared network domains; conformance tests; permission diff against the previous release. - Human source review of every release, reading the diff since the last reviewed release. Higher-risk combinations (document read with network, account use) need a second reviewer.
- After publication: user reports, revocation of a release digest that takes effect at next launch or online check (T10), and the runtime limits of T05/T06 regardless.
T06 session proposal: runtime and safety
Status: proposed 2026-11-09 after an all-perspective review (end user mid-edit and mid-render, plugin author debugging, malicious author, app maintainer, reviewer, support). Builds on T02 (styles, determinism), T04 (dispatcher, transactions) and T05 (grants with generation). Not accepted.
Evidence
All three existing hosts already use the same engine, wasmi 2 (pure-Rust interpreter), with fuel and StoreLimits, but each configured it differently:
EffectCraft ce9eaec crates/plugin/src/wasm.rs |
PhotoCraft 655295b2 crates/plugins/src/runtime.rs |
FigCraft 0e86f359 crates/plugin/src/sandbox.rs |
|
|---|---|---|---|
| Fuel | 50 M base + 20 k per pixel | 50 M base + 4 k per sample | 1 G per run, +10 k per host call, +1 per byte copied |
| Wall time / cancel | None | Fuel given in 20 M slices with a deadline check between slices (resumable calls) | None |
| Memory | 1 GiB per instance | Per instance and total across parallel bands; band parallelism limited to fit | Per instance; 1 memory, 4 tables, 100 k elements |
| Recursion, strict limits | Not set | enforced_limits(strict), recursion depth |
Not set |
| Imports | None allowed | ABI imports | Fixed import table |
| Instance reuse | Pooled across calls (pool: Mutex<Vec<Inst>>) |
Per run | Per run |
| wasmi features | deterministic |
stable |
stable |
EffectCraft also runs native external helpers as child processes (crates/helper-host), designed for crash containment (an OpenFX host, for example), not security.
PhotoCraft already has the most complete pattern; the shared host should start from it.
1. One engine profile, shared
craft-ext-host owns one wasmi configuration used by every app: fuel on, strict enforced limits, recursion cap, a pinned list of allowed WebAssembly features (verify against wasmi 2 before fixing the SDK template, T03), no threads, deterministic mode for transforms (T02 obligation). Module validation at load: size, function, table, memory and import caps; unknown imports refuse the module. Validated modules are cached per release digest. Apps cannot loosen the profile; they choose budget numbers within it.
Engine-neutral host trait, so a second engine can be added later behind the same contract (Q1).
2. Budgets
| Budget | Mechanism | Why |
|---|---|---|
| Instructions | Fuel scaled by work size (per pixel, sample, cell, node) | Deterministic, same on every platform including web |
| Wall time and cancel | PhotoCraft's fuel slices with deadline and cancel check between slices | Responsive cancel and a real "took too long" without threads or signals |
| Memory | Per-instance cap plus total across parallel instances; parallelism reduced to fit | Many render threads cannot multiply memory |
| Host calls | Fuel per call plus per byte copied (FigCraft) | A plugin cannot spin the host |
| Output | Size and shape validated by the contract before use | Garbage never reaches the document |
Profiles (numbers measured in T16, not guessed here): preview (short, keeps playback smooth), final render (generous), session command (short, holds the document), job (long, cancellable). The GUI offers "Allow more time" per plugin, recorded like a grant; headless runs take an explicit flag.
3. Instances
- Transforms: one instance per render thread; an instance is reused only within the same document and job, and reset otherwise. EffectCraft's cross-call pool would let state from one document reach another and breaks the determinism promise; it changes to per-job reuse.
- Session plugins: one instance per package per app window, on a worker thread, never the UI thread. Panels draw from the last committed state, so a busy plugin never freezes the app.
- A trapped or over-budget instance is discarded, never reused.
4. Failure contract
| What happens | Result for the user | Document |
|---|---|---|
| Crash (trap) | Message naming the plugin; in preview the effect shows an error badge and passes the frame through unchanged | Edit rolled back |
| Too slow / too much memory | "Took too long" with "Allow more time" in the GUI | Rolled back |
| Invalid output | "Returned an invalid result" | Nothing committed |
| Forbidden call | Structured denial the plugin can handle; not a crash | Unchanged |
| Permission revoked mid-run | Next host call fails; job cancelled | Rolled back |
| Final render or export with a failed plugin | Q3 | — |
| Repeated failures | After several consecutive failures in a session the contribution pauses for the session with a notice; it stays installed and enabled | — |
| App crashed while loading plugins | Next start offers safe mode with plugins off (detail in T16) | — |
The host never panics because of a plugin: wasmi is safe Rust, every boundary returns errors, and the existing command guard remains a last resort.
5. Proof
craft-ext-conformance includes a hostile-module suite: infinite loop, memory bomb, deep recursion, huge tables, unknown import, trap in every callback, invalid outputs, calls after revoke, cancel during work. It runs in CI on every supported desktop target and the web build. Protection is claimed only where the suite passes.
6. Native, GPU and audio
- Native code (EffectCraft helpers, OpenFX hosts, VST): cannot be sandboxed by wasmi; a child process contains crashes, not malice. Q2.
- GPU: plugins call host GPU operations (built-in kernels exposed as operations). Plugin-supplied shaders are a later backend after driver-hang and resource evidence.
- Real-time audio: wasmi cannot promise audio deadlines; stays excluded (T02) until SoundCraft evidence.
T06 outcome (2026-11-09)
User chose wasmi only (A), native plugins in the store after review (C) and failing exports on plugin failure (A). Native safeguards: out of process only through a versioned helper protocol (EffectCraft helper-host design), never loaded into the app; the store builds native binaries from the tagged source for each platform, with no author-uploaded binaries or prebuilt blobs; two reviewers with a full first review; a distinct "Full access to your computer" label and consent screen; updates need user confirmation; revocation kills the process; OS confinement (macOS App Sandbox, Windows AppContainer, Linux Landlock or bubblewrap) applied per platform as proven, enforcing the declared permissions. Until confinement is proven on a platform, the protected core holds for native plugins only through review.
Store role corrected (2026-11-09)
The user corrected the store's role: the store is a listing, not a builder, host or guarantor. Plugins are fetched from the author's GitHub and Releases. Before listing, maintainers check the package conforms to Craft formats and rules and run a light test. There are no restrictions on what a plugin may do and the project takes no responsibility for it. This supersedes, in the open-ecosystem section and the T06 outcome above: mandatory reproducible rebuild by the store, human source review of every release, two reviewers, store-built native binaries and OS confinement as a store requirement. It matches the earlier settled distribution direction (publisher GitHub Release assets and a reviewed metadata repository).
What remains, because it is cheap and protects users without restricting authors:
| Kept | Why |
|---|---|
| Catalogue record pins the exact asset digest that was checked | If the author's release or account is later changed or compromised, the app refuses the swapped file instead of installing unchecked code |
| Bot checks: manifest validator, licence file MIT/Apache-2.0, public source link, digest, load and smoke test in the reference host | This is the "conforms to our formats and rules" check and the light test |
| Labels: "Native: full access to your computer", "Not reviewed" for file installs | Users know what they are running; no responsibility claimed |
| Delisting and digest revocation | The project can remove a listing it learns is malicious without taking on review duties |
| Runtime sandbox and permissions for WebAssembly plugins (T05/T06) | Protects users by design, costs authors nothing, and is what makes light review acceptable (Q asked) |
T07 session proposal: package identity and compatibility
Status: proposed 2026-11-09 after an all-perspective review (author renaming or moving a repo, author selling a plugin, impersonator, user with an old project, user on an older app, store maintainer, app maintainer changing a contract). Builds on T01 lifetimes, T03 contract versions, T06 engine profile and the corrected store role. Not accepted.
Evidence
- craft-extensions
a6c5fae: packageidis a lowercase reverse-domain string (org.example.tone) from a tiny alphabet so look-alikes cannot exist (crates/ext-core/src/id.rs); first-party prefixes are reserved;versionis strictmajor.minor.patch;compatper app hasmin_appand a plug-ininterfacenumber;provenancehas source and commit; every file is listed with SHA-256; unknown fields are ignored. - EffectCraft
ce9eaec: plug-in manifestidis reverse-domain (org.example.posterize),ec.reserved,api1 or 2, free-textversion(crates/effects/src/plugin.rs:168-183). Projects save onlyEffect { effect: "<id>" }, with no package or version (crates/project/src/props.rs:183-186). - FigCraft
0e86f359: reverse-domainid,api1 to 4. - The design drafts used a package UUID (
pkg:<uuid>/<contribution>); no app uses one.
1. Identity: one readable ID, ownership checked by the store
- Package ID stays the existing reverse-domain form. Its namespace is verified the way Flathub does:
io.github.<owner>.<name>is accepted when the listing's GitHub repository belongs to<owner>; any other domain is verified once by a maintainer (for example a DNS TXT record or a file on the domain). First-party prefixes stay reserved. No UUID. - Contribution ID:
<package-id>/<contribution>, for exampleio.github.ink.grain/halftone. Unique within the package and never reused for a different behaviour. - Release: package ID + version + the asset digest pinned in the catalogue record.
- IDs never change. Display names, repository URLs and descriptions can.
- A local file using an ID that is installed from the store is refused unless the user removes the store copy first (no silent takeover).
2. Moves, renames and owner changes
| Event | Result |
|---|---|
| Repository renamed or moved on GitHub | Maintainer updates the listing URL; the ID stays; users notice nothing |
| Plugin renamed | Display name changes; ID stays |
| Ownership transferred (sold, handed over) | Catalogue records the transfer. Users are told "has a new owner" before the next update installs (Q2) |
| Author abandons it | Stays listed with "no updates since "; a fork is a new ID |
3. Versions and compatibility
A plugin declares, per app, the contracts it uses with major and minimum minor (recorded automatically by craft-ext pack from the inventories, T03), its style, and for native plugins its platforms. App version is an optional extra lower bound for workarounds, not the main rule (Q3).
| Check | Where | Outcome |
|---|---|---|
| Manifest schema | Install | Newer schema than the app knows: "Update the app to install this". Critical changes always bump the schema, so unknown critical fields cannot be skipped |
| Contract major/minor | Install and load | Same major and app minor ≥ required: compatible. Otherwise per contribution: unavailable with "needs ; you have : update the app" or "this plugin is too old for this app" |
| Engine features and imports | Load (T06) | Refused with the feature named |
| Platform (native) | Install | Only a matching artifact is offered |
| Per app, per contribution | Setup | A multi-app package can work fully in one app and partly or not at all in another; each contribution shows its own reason |
The outcomes are: compatible, partly compatible (some contributions unavailable, each with its reason), incompatible (with what to update). Never a silent half-load.
4. Saved references in projects
A project stores, for each plugin feature: contribution ID, the exact version used, the contract version, parameters and the plugin's state with its schema version. On reopen the app uses the installed release if it is the same major and not older than saved; otherwise it shows a placeholder that keeps all data (T13). EffectCraft's bare effect id is migrated through legacy_ids declared in the new manifest; a package may only claim legacy IDs under its own namespace, so nobody can claim ec.* or another author's effects.
5. Existing systems
| Today | Becomes |
|---|---|
craft-extensions id, version, files with SHA-256, provenance |
Kept as is |
compat.min_app + interface |
Contracts per app with major/minor; min_app optional |
EffectCraft/FigCraft api numbers |
Legacy app profiles (T02) expressed as contract versions |
EffectCraft project Effect { effect } |
Contribution ID + version + state, through legacy_ids |
| Unknown fields ignored | Still ignored for optional data; critical changes bump schema |
T08 session proposal: store and lifecycle
Status: proposed 2026-11-09 after an all-perspective review (user with several apps open, long export during an update, launcher and CLI writing at once, old and new app versions side by side, crash mid-install, low disk, support). Builds on T01 lifetimes, T05 grants, T06 native label, T07 identity. Not accepted.
Evidence (craft-extensions a6c5fae, crates/ext-store)
Already good and kept: one shared folder under the user's local data, CRAFT_EXT_DIR override (location.rs); immutable packages/<id>/<version>/; unpack and check in staging/ outside the lock; a short .lock for the move and the state write; atomic state replacement with a generation counter that apps poll; downgrade refused; first-party never replaced by a file; readers never write and treat unreadable data as absent (store.rs:1-12, reader.rs, state.rs).
Gaps: install enables every app the manifest lists (store.rs:198-200); update deletes the old version folder immediately after the state write, even if an app or export is using it (store.rs:209-211); records hold no digest, source or listing, grants or per-app choices other than enable and theme (state.rs:23-44); one schema number, so a newer state makes older apps see nothing.
1. Five kinds of state, each with one owner
| State | Lives in | Owner | Changes when |
|---|---|---|---|
| Release bytes | packages/<id>/<version>-<digest>/, never edited |
Store | Installed; deleted only by cleanup |
| Package record | state.json |
Store | Install, update, uninstall: source (store listing or local file), label, releases kept, default release |
| Per-app setup | state.json, keyed by app |
User through any app, launcher or CLI | Enable per contribution, settings, theme choice, optional pinned release, grants (T05), "Allow more time" (T06) |
| Leases | leases/<process>.json |
Each running app, CLI or job | Created when it loads a release, removed on exit; dead processes' leases are ignored |
| Caches | cache/ |
Any app | Validated or compiled module data; always safe to delete |
2. Transitions and what a crash leaves
| Transition | Steps | Crash at any step leaves |
|---|---|---|
| Install | Download from the author's release → check pinned digest → stage → validate → move into packages → write state. Enables nothing |
Previous state; leftover staging or an unrecorded release folder is cleaned on next start |
| Setup in an app | Choose contributions, grant permissions | Previous setup |
| Update | Install new release beside the old one → state default = new → per-app choices carry over; new contributions start off; a widened permission or new owner keeps that app on the old release until the user accepts (T05/T07) | Old release still default |
| Running work during update | A running export or job keeps its lease on the old release and finishes with it; new work uses the new default (Q1) | — |
| Roll back | "Use previous version" pins the kept previous release for that app | — |
| Disable in an app | Setup off; grants kept | — |
| Uninstall | Record, setups and grants removed; bytes deleted once no lease uses them; projects show placeholders (T13) | Record still present |
| Cleanup | Deletes releases that are not default, pinned, previous-kept (Q2) or leased; caches first under low disk | Nothing lost: cleanup only deletes unrecorded or unreferenced data |
Low disk: an install checks free space for the archive and the unpacked size before downloading and fails with a clear message.
3. Several writers, several versions
- Writers (apps, launcher, CLI) keep the existing short lock and atomic replace with
generation. An OS file lock is released automatically if a writer crashes. - Schema evolution uses two numbers, as SQLite's file header does:
write_versionandread_version. Additive changes raise onlywrite_version, so older apps can still read; an app refuses to write a state whosewrite_versionis newer than it understands (it would drop fields) and asks the user to update it. Only a breaking change raisesread_version. - The one-time move from today's schema 1 keeps everything readable by apps not yet updated: what old apps understand (installed list, enable, theme) stays in place.
4. Updates
Checking for updates reads the catalogue (T09/T10). The store supports automatic and ask-first per package and per app; the default is Q3. Native plugins and new owners always ask (T06/T07).
T09 session proposal: GitHub distribution and catalogue
Status: proposed 2026-11-09 after an all-perspective review (first-time author, regular author, maintainer, bot, end user browsing offline, impersonator, author who deletes their repo, attacker who takes over a renamed GitHub account). Starts from the catalogue design, adjusted to the settled decisions: store lists only (no building, hosting or responsibility), light review, MIT/Apache, native allowed, reverse-domain IDs (no UUID), always-ask updates, any listed version installable. Not accepted.
Evidence
- craft-extensions
a6c5faeext-core/src/index.rs: an index with version, expiry, rollback refusal and revocations byid+below; unsigned; entries carry URL, size and apps. - craft-launcher
c9c3acacrates/native/src/install.rs,http.rs: GitHub Release download with resume, size cap and SHA-256; to be extracted for shared use (W6). - EffectCraft
ce9eaeccrates/engine/src/system/library.rs: its ownindex.jsoninstorytold/effectcraft-plugins, fetched unsigned withcurl. To be folded into the one catalogue.
The path
author repo ── craft-ext prepare-release ──▶ GitHub Release on the AUTHOR's repo (zip; native: one zip per platform)
│ │
└── PR to catalogue repo: releases/<version>.toml
▼
bot (no secrets, read-only): download, digest, validate, licence, namespace, smoke test → report
▼
merge rule (Q1) ──▶ publish job: catalogue.json regenerated and signed (T10)
▼
apps / launcher / CLI: fetch catalogue (no login) → browse → choose version → download from author's
GitHub → check pinned digest → store (T08) → setup per app (T05)
Records (metadata only; the repository never holds plugin files)
| Record | Fields |
|---|---|
| Publisher | GitHub login and numeric owner ID, display name, official flag (maintainers only), status |
| Package | Package ID (T07), repository owner/name and numeric repository ID, licence (MIT and/or Apache-2.0), apps, summary, legacy IDs, native flag |
| Release | Version, tag and commit, per platform: URL, size, SHA-256; contracts per app; permissions; bot report link; channel |
| Revocation | Match by digest, package and version range, or publisher; severity advisory, block-new, disable; reason |
| Transfer | Old and new owner, date, maintainer; drives the "new owner" notice (T07) |
All approved releases stay listed so users can choose any version (T08 Q2).
What the bot checks
Shared validator (same code as craft-ext check and the installer); pinned digest and size; licence file and SPDX expression MIT and/or Apache-2.0, bundled dependencies within the house allowlist; public source link at the tag; namespace ownership (T07); permission and contribution diff against the previous release; WebAssembly smoke test in the reference host. Native releases: static checks, and the smoke test only on an ephemeral runner with no secrets or write permissions. The bot never holds credentials that a plugin could steal.
When GitHub changes underneath
| Event | Result |
|---|---|
| Release or repository deleted by the author | Installed copies keep working; that version shows "no longer available from the author"; nothing is mirrored |
| Asset replaced after review | Digest mismatch: the app refuses it; bot flags the listing |
| Repository renamed or moved | Numeric repository ID matches; bot updates the URL |
| Account deleted and the name re-registered by someone else | Numeric owner ID differs: listing frozen until a maintainer checks (blocks repo-jacking) |
| GitHub unreachable or offline | Browse from the last fetched catalogue; installs and updates wait; installed plugins unaffected |
Author effort
One command (craft-ext prepare-release) writes the zip and the record; the template GitHub Action uploads the release; the author opens the catalogue PR. Immutable releases are recommended, not required, since the digest already pins the bytes.
T10 session proposal: authenticity and incident operations
Status: proposed 2026-11-09 after an all-perspective review (attacker with an author's GitHub account, attacker with a maintainer's account, leaked signing key, malicious plugin discovered after thousands of installs, offline user, maintainer on call). Builds on T09 (bot auto-merge, pinned digests, numeric GitHub IDs) and the store's light-responsibility role. Not accepted.
Evidence
- craft-extensions
a6c5faeext-core/src/index.rs:1-6: version, expiry and rollback refusal exist; signatures are "a later gate"; revocation onlyid+below. - craft-launcher
c9c3aca: the app list is built in (crates/core/src/catalog.rs); macOS builds checked against an Apple team ID; Flatpak OCI signatures for Linux. No signed metadata format exists to reuse. - EffectCraft's plug-in index is unsigned and fetched with
curl.
Threats and the defence for each
| Threat | Defence |
|---|---|
| Catalogue changed by someone with repository or hosting access | Apps accept only signed metadata; the trust root ships inside the signed app; hosting gives no authority (Q1) |
| Author's GitHub account taken over, publishes a routine-looking update | The bot would auto-merge it (T09). Auto-merged updates are held before users see them (Q2); the author and watchers are notified by the catalogue PR; any report or maintainer can block during the hold |
| Release file swapped after the check | Pinned digest: refused |
| Old or frozen catalogue replayed to hide a revocation | Version and expiry already in the index; expired metadata is shown as stale and cannot authorize new installs |
| Online signing key leaked | Offline root keys (held by two or more maintainers on hardware keys) rotate it; apps follow without an app update (Q1 A) |
| Malicious plugin discovered | Revocation, below |
Signing and key custody
- Online key: signs each publication and refreshes expiry; lives only in the protected publish job's environment, which requires a maintainer approval.
- Offline root: two of three maintainers must sign root changes; stored on hardware keys; recovery rehearsed once before launch.
- Operational owner: the catalogue maintainers, named when the repository is created (T09 Q2).
Revocation
| Severity | Effect | Who can issue |
|---|---|---|
| Advisory | Warning on the listing and in the app | Any maintainer |
| Block new | No new installs, enables or updates to the matched releases | Any maintainer, immediately |
| Disable | Installed matched releases stop loading at the next check; running work stops at the next host call (native: process killed); an export in progress fails naming the reason (T06 Q3) | Any maintainer, immediately; reviewed by a second maintainer within a day |
Matches: exact digest (also applies to the same bytes installed from a file), package version range, or a whole publisher (account takeover). Apps check the small revocation list at start and every few hours when online; known revocations are kept across repair and restore. A revoked plugin's data and project references are never deleted; projects show a placeholder (T13).
Incident steps (account takeover example)
- Report arrives (catalogue issue form, or private security contact for sensitive reports).
- Maintainer issues block new on the publisher immediately; disable if malicious code shipped.
- Listing shows a banner; apps show a notice on next check.
- Author regains the account; a recovery release gets a quick human look (as for first listings) before the block lifts.
- Short public note in the catalogue repository.
Offline
Installed plugins keep working offline with the last known revocations applied. Unknown revocations cannot be known; the next online check applies them.
T11 session proposal: search and management UX
Status: proposed 2026-11-09 after an all-perspective review (new user looking for a glow effect, user of several apps, user offline, keyboard and screen-reader user, non-English user, author wanting visibility, maintainer, support). Builds on T05 (consent), T06 (labels), T07 (compatibility outcomes), T08 (lifecycle), T09/T10 (catalogue, holds, revocation). Not accepted.
Evidence
- FigCraft
0e86f359: a "Manage plugins" window with a Browse tab; Install first shows permissions, downloads are cancellable and the window stays responsive (crates/ui-egui/src/plugins_browse_tests.rs:1-5). - EffectCraft
ce9eaec: its own Plug-in Library in settings and dialogs (crates/ui-egui/src/panels/settings.rs,dialogs.rs). - Each app builds its own manager; nothing is shared.
1. One manager component, shown in every app and the launcher
A shared egui component in craft-extensions (T03 A), using craft-libs craft-i18n for text. Inside an app it shows that app; the launcher shows all apps. The CLI offers the same actions (<app>-cli plugin search|info|versions|install|setup|grant|update|remove) through the same client.
2. Screens
| Screen | Content |
|---|---|
| Browse | Search box; filters: kind (effects, tools, panels, themes, resources), "works in this app", native; rows show name, summary, author, stars with date, labels (Official, Native: full access, Not reviewed) and a compatibility badge |
| Detail | Description, screenshots (pinned in the record, loaded on demand), what it can access in plain sentences (T05), per-app compatibility with reasons (T07), versions to choose from (T08), licence, source link, last updated, release notes |
| Install and setup | Install downloads (cancellable, shows progress) and then offers "Set up in ": contributions on/off and permissions in one sheet. Other apps show "New plugin ready to set up" the next time they open |
| Installed | Per app: on/off per contribution, permissions with last use and revoke, version (choose another), update available, remove, problems |
| Updates | Badge with count; each update shows release notes and highlights more permissions, new owner and native. Always asks (T08 Q3) |
| Problems | Failed, paused, incompatible or blocked plugins, each with the reason and a fix button (update the app, choose a version, allow more time, remove); "Start in safe mode"; "Report plugin" link to the catalogue's form |
3. Ranking
Filter (query, this app, kind, compatible with this app and platform, not blocked) → relevance tier (exact name or ID, prefix, text) → official first within a tier (Q1) → repository stars → newer approval → ID for a stable order. Stars are fetched centrally by the publish job, never by desktops.
4. Built-in search suggestions (Q2)
When a built-in search (effects, commands) has no match, the app can show matching plugins from the cached catalogue: "No built-in match. 3 plugins in the store." The search never leaves the machine; a setting turns it off.
5. Offline, accessibility, language
- Offline: browse the cached catalogue with its date; installs wait; installed plugins work.
- Keyboard and screen readers: every action reachable by keyboard, labels and states exposed through the toolkit's accessibility support; labels never rely on colour alone.
- Language: app text through
craft-i18n; plugin text in the author's language, with optional per-language fields in the release record. - No account needed for anything public.
T12 session proposal: plugin UI and interactions
Status: proposed 2026-11-10 after an all-perspective review (effect author who wants no UI code, panel author, tool author drawing on the canvas, user who relies on their shortcuts, keyboard and screen-reader user, user switching documents mid-gesture, theme author, CLI user). Builds on T01 (protected core, additive namespaces), T04 (one undo step per invocation), T05 (host-drawn prompts), T06 (worker thread, budgets), T08 (reload at safe points). Not accepted.
Evidence
- House rule (Rust repositories, rule 4): native Craft apps have no webview, Tauri or Electron, and no handwritten JavaScript. Plugin UI therefore cannot be HTML.
- EffectCraft
ce9eaec: effect parameters are declared as data (PluginParamKind: slider, angle, point, 3D point and more) and the host builds the controls (crates/effects/src/plugin.rs:55-110). - FigCraft
0e86f359: panels and settings as data with state kept between callbacks and one undo step per editing callback (API 2); canvas widgets drawn from plugin descriptions, clicks and hover as one undo step each, kept through undo, save and reload; junk descriptions, runaway callbacks and forged widget data refused (API 3) (crates/engine/src/plugin_panels_tests.rs:1-4,widgets_tests.rs:1-4). - craft-libs:
craft-keymapalready has default bindings, user overrides, conflicts, reserved system chords and a shortcut editor model;craft-menubuilds menus fromCommandRefs;craft-uihas docking, panes, focus, IME and themes.
1. Host draws everything; plugins describe
Plugins return data; the app draws it with its own widgets. Consequences: plugin UI matches the app and its theme, is accessible and localized through the same toolkit, cannot imitate a host permission prompt, and a slow plugin never freezes the UI because nothing runs on the UI thread. This is the approach of Blender's layout API, Slack Block Kit and Adaptive Cards.
2. UI contribution kinds
| Kind | What the author writes | Host behaviour |
|---|---|---|
| Effect parameters | #[derive(craft::Params)] only |
Controls, keyframes, expressions and presets come from the host. Most effect authors write no UI code |
| Commands | A command contribution | Appears in menus, command search, CLI and MCP (T04) |
| Menu items | Placement in a declared extension point (Q3) | Added after the built-ins, grouped under the plugin; never removes or reorders built-ins |
| Shortcuts | Optional suggested default (Q2) | Through craft-keymap; user can rebind anything |
| Panels and dialogs | A tree: rows, columns, labels, buttons, fields, sliders, lists, tables, images from the package, progress, plus a custom canvas element (Q1) | Docked with craft-ui; plugin dialogs carry the plugin's name and icon so they cannot pass as the app |
| Inspector and context-menu sections, settings pages | Same tree | Shown in the host's places |
| Canvas overlays and widgets | Draw lists (shapes, paths, text, images) in document coordinates, bounded in count | Host renders and hit-tests; hover and click arrive as events |
| Pointer tools | begin, update, commit, cancel | Host captures input; updates are coalesced to the latest so the pointer stays smooth; preview through an overlay; commit is one undo step; Escape or losing capture cancels with the document unchanged |
3. Events, lifecycle and undo
- Every UI event is an invocation (T04) on the plugin's worker thread under the command budget (T06). While it runs, the control shows busy; the rest of the app works.
- Open creates the session instance; close disposes it and drops its callbacks. Switching document sends a scope change; a gesture in progress is cancelled first.
- Update or disable closes the plugin's UI with a notice and reopens it at the next safe point (T08).
- Edits from a callback or gesture are one undo step labelled with the plugin. UI-only state is not in undo.
- Where things are kept: panel placement by the host per app; plugin settings in its private storage per app; widget data in the document (as FigCraft does).
- Headless (CLI, MCP, render): UI contributions do not exist; commands remain available.
4. Accessibility, language, themes
The SDK refuses a control without a label at build time. Text uses the package's localization keys with the host choosing the language. Themes apply automatically because the host draws.
Existing app plugin systems are replaced (2026-11-10)
User direction: the plugin systems apps have today (EffectCraft WASM ABI v1/v2, helpers and Plug-in Library; FigCraft APIs 1 to 4; PhotoCraft filter ABI) will be removed completely and replaced by this design. Wherever earlier sections cite them, they are lessons, not compatibility constraints. Superseded: T02 legacy app profiles, the T05 migration table, T07 legacy_ids, folding EffectCraft's index into the catalogue (T09). Old projects referencing removed plugins open with placeholders that keep their data (T13).
T13 session proposal: live projects and reliable output
Status: proposed 2026-11-10 after an all-perspective review (artist reopening last month's project, freelancer sending a project to a client without the plugin, studio render farm, two collaborators, plugin author changing their saved-state format, user offline before a deadline). Builds on T06 Q3 (failure fails export), T07 (saved references), T08 (current release only, any version downloadable), T10 (revocation), and the replacement of existing plugin systems. Not accepted.
Lesson from today's code
EffectCraft ce9eaec crates/render/src/pipeline.rs:622-632 drops any effect whose ID it cannot find (filter_map on find(effect)), so a project with a missing plugin renders and exports "successfully" without it. The new design must make that impossible.
1. What a project stores per plugin feature
Contribution ID, exact version used, contract version, parameters, the plugin's own state with its schema number (T07), and a plugin list at the project level (ID, version, catalogue link or "local only") so the app can tell what is needed before loading anything. Grants are never stored (T05).
2. Reopening
| Situation | Result |
|---|---|
| Same or newer release, same major, installed and set up | Used. If the version differs: a quiet note "Made with Grain 1.2, using 1.4" (Q1) |
| Saved state schema older | Plugin's migrate(old_schema, data) runs; the result is saved only when the user saves. Migration failure → placeholder |
| Installed release older than saved, or different major without declared migration | Placeholder: "Needs Grain 1.2 or newer" with Update |
| Not installed / not set up in this app | Placeholder with Install or Set up (one prompt lists all missing plugins: "This project uses 3 plugins") |
| Revoked | Placeholder with the revocation reason; data kept |
| Plugin from a removed old system | Placeholder; data kept |
A placeholder keeps everything: parameters, state, keyframes, position in the stack. Preview passes the input through with a badge; editing everything else works; saving writes the plugin's data back byte for byte. Nothing is ever silently dropped.
3. Output
- Final render and export with any placeholder, failed or blocked plugin fails before starting, listing the plugins and how to fix each (Install, Update, Set up). Same in the CLI and render queue, with the exact
plugin installcommands. - Preview may use draft quality and scale; final render always runs at final quality. Plugins receive a
qualityhint; caches key on it, so a preview frame is never reused as final. - Caches key on release digest, contract version, parameters, inputs and quality. An update or version change invalidates exactly that plugin's results. Determinism (T02) makes caches valid across machines.
4. Portability
- Bake (Q2): "Bake plugin result" renders a plugin feature to pixels, frames, geometry or values as the app's own data, so the project opens anywhere. The original plugin feature is kept, switched off, so it can be un-baked. This is After Effects pre-render, Photoshop rasterize and a DAW's freeze.
- Projects do not embed plugin files (Q3). The plugin list carries catalogue links; the receiver installs through the store or a file with their own consent.
- Collaboration: plugin edits go through the same operations (T04), so they merge, sync and undo like built-in edits. Plugin state must be plain serializable data, never memory addresses or machine paths (files are tokens, T05).
T13 outcome (2026-11-10)
Q1 A and Q2 A as proposed. Q3 changed to B, off by default: an explicit "include plugins" option when saving or collecting files puts the plugin archives in the project. On open they are listed, never installed or run automatically. "Install from project" is an ordinary file install through the store's validation; an archive whose digest matches a catalogue listing is treated as that listing, otherwise it is "Not reviewed" (native ones also "full access"); revocation applies by digest; setup and permissions as usual.
T14 session proposal: typed resources, themes and workflows
Status: proposed 2026-11-10 after an all-perspective review (colourist installing a LUT pack, theme author, user with a broken theme, person installing a 3 GB model, workflow author, user running a downloaded workflow, translator, user with a hostile file). Builds on T02 (data style, typed resource contracts), T05, T08, T13. Not accepted.
Evidence (platform code to keep, not app plugin systems)
- craft-extensions
a6c5fae:Kind::ThemeandKind::Resource; resources capped at 512 files, 64 MiB each, 256 MiB total (manifest.rs:44); the shared theme is a small palette every app maps onto its tokens plus optional per-app overrides, and a theme that breaks WCAG 4.5:1 contrast cannot be installed (palette.rs:1-6). - craft-libs
craft-keymaphas named shortcut profiles and imports;craft-ai-coreis the interim shared model store contract. - GitHub release assets are limited to 2 GiB each.
1. One rule for every data kind
Data packages contain no code. Each kind has one importer that validates hostile input with size, count, dimension and nesting limits; installation never runs anything; a file that fails validation is refused with the reason. Shared kinds have one importer in craft-extensions or craft-libs used by every app; app-only kinds have the app's importer.
| Kind | Importer | Notes |
|---|---|---|
| Themes | Shared palette + per-app overrides (exists) | Never auto-activated; invalid → app keeps its own look; contrast enforced; scope Q3 |
| Effect and tool presets | App | Refer to a contribution ID + parameters; a preset for a missing plugin shows Install |
| LUTs, ICC profiles, gradients, swatches, patterns | Shared | Typed resource contracts from T02 |
| Brushes, shape and symbol libraries, templates | App | Templates are documents opened through the app's normal loader with its limits |
| Fonts | Shared font store | Licence from the house allowlist (OFL, etc.); usable inside Craft apps, not installed system-wide |
| Keymap profiles | craft-keymap profiles |
Applied only when the user chooses; cannot bind management or hidden commands |
| Localization packs | craft-i18n |
Translate app text, but never permission, consent or warning text, which always comes from the app's own translations, so a pack cannot make a dangerous plugin sound harmless |
| ML models | craft-ai-core store |
Large; see section 2 |
| Workflows | App or shared graph contract | Section 3 |
2. Large resources
A package may reference large files (models, big template libraries) by URL, size and SHA-256 instead of carrying them (GitHub's 2 GiB asset limit; avoids huge installs). States: not downloaded, downloading, ready, failed. Download happens on first use with the size shown (Q2), is resumable, checked against the digest, and stored content-addressed so two packages sharing a model keep one copy. Removed when no installed package refers to it. Offline before download: the feature says it needs a download.
3. Workflows
A workflow is a graph of operations (T04) and plugin contributions with typed inputs and outputs. It can be inspected without running: the app lists the operations, plugins and permissions it needs. Running is a job (T15) with progress and cancel. Authority (Q1): it runs as its own package with the permissions it declares, approved at setup like a plugin, so a "data-only" download cannot use the user's full power just because the user pressed Run. Missing nodes become placeholders (T13); the workflow cannot run until they are installed.
T15 session proposal: automation and jobs
Status: proposed 2026-11-10 after an all-perspective review (script author, AI agent over MCP, user with the app open while an agent edits, render-farm operator, another local program or web page trying to reach the app, another account on a shared machine, plugin). Builds on T04 (one operation path, automation authority Q1 A, management scope), T05 (CLI grant commands), T06 (budgets), T13 (export fails on missing plugins). Not accepted.
Evidence
- EffectCraft
ce9eaec: the control server listens on TCP127.0.0.1:9877with no token (apps/effectcraft/src/control_server.rs:27-34; a test sends a request with a foreignOrigin, line 183). MCP long renders run as a background job withnotifications/progressand stop onnotifications/cancelled, deleting partial output (crates/automation/src/long_job.rs:1-6). - FigCraft
0e86f359: the MCP backend attaches to the running app over plain TCP (crates/mcp/src/backend.rs:96-123). - PhotoCraft
655295b2: per-commandauthorize_*for automation (crates/automation/src/workspace.rs:327-398).
Any local program, any other account on the machine, and in some cases a web page can reach today's open ports.
1. Three environments, one operation set
| Environment | What it is | Plugins |
|---|---|---|
| Fresh CLI | A headless process opening a project | Installed releases set up for that app, same eligibility as the GUI; never prompts |
| Attached | Controls the running app | Whatever the app has loaded |
| Server | A long-running headless app (render node) | As fresh CLI |
All three call the same operations (T04) with the same results and error codes. Existing CLI commands stay as aliases of generated operations. A fresh CLI refuses to write a project that is open in a running app (per-document lock file) and suggests --attach, so an agent cannot overwrite unsaved work.
2. Attaching safely (Q1)
- Transport: a Unix domain socket in a user-only directory (macOS, Linux) or a named pipe restricted to the user (Windows), plus a random per-session token in a user-only file. Browsers cannot open these, and other accounts cannot reach them. This is how Docker, VS Code's CLI and language tools attach. No network port by default; remote server mode is a later explicit configuration (TLS and token).
- Authority: the user's document authority; management operations only after in-app approval once per session (T04 Q1).
- While an external client is connected, the app shows " is controlling EffectCraft · Stop" (Q2).
- Several clients may attach; each is its own principal; edits are serialized by the dispatcher.
- Plugins have no sockets and never receive the token (T04).
3. Jobs
One job model in every environment: ID, owner, state (queued, running, succeeded, failed, cancelled), progress, outputs, structured error.
| Client | Progress | Cancel | Disconnect or exit |
|---|---|---|---|
| CLI | --json progress lines; human progress otherwise |
Ctrl-C cancels cleanly | Fresh: the job ends with the process |
| MCP | notifications/progress |
notifications/cancelled |
Attached: Q3 |
| Attached | jobs list, jobs wait <id> |
jobs cancel <id> |
Q3 |
App quit with running jobs: the GUI asks; headless on SIGTERM cancels cleanly and exits with the cancelled code.
4. Outputs and errors
- Outputs are written to a temporary name and renamed when complete, so an incomplete file never looks finished; cancelled or failed jobs delete partial output. Results list paths, sizes and digests.
- Stable exit codes shared with MCP error data: 0 succeeded, 1 failed, 2 usage, 3 input required (lists what is missing), 4 plugin missing or not permitted (prints the
plugin installorplugin grantcommand), 5 cancelled.
T16 session proposal: performance, offline behaviour and diagnostics
Status: proposed 2026-11-10 after an all-perspective review (artist scrubbing a 4K timeline with three plugin effects, export on a laptop with 8 GB, user on a plane, plugin author chasing a slowdown, support helping a user whose app will not start, privacy-minded user). Builds on T06 (budgets, profiles, wasmi), T08, T10, T13, T14, T15. Not accepted.
Evidence
- The workload profiles draft: interactive, preview, background/export and real-time audio, with per-instance and app-wide accounting and explicit raises.
- EffectCraft
ce9eaechas no safe-start mode; no shared log rotation or support bundle was found in the audited apps.
1. Budget numbers come from measurement
craft-ext-conformancegains a benchmark set: reference plugins (blur, halftone, LUT apply, a panel callback, a geometry edit) run on named reference hardware in CI.- Default budgets = measured cost of the reference workload × generous headroom, per profile (T06). Raised per plugin by the user ("Allow more time"), never beyond the host's maximum.
- App-wide: plugin memory has a total ceiling as a share of system memory; parallel instances reduce to fit (PhotoCraft's band rule). Interactive and preview work outranks background export in the shared scheduler so a long export never makes scrubbing stutter.
- Engine re-evaluation trigger for T06 Q1: when a reference plugin effect at 4K is several times slower than the equivalent built-in and drops preview below real time on reference hardware, evaluate a compiling engine on desktop behind the same host trait.
2. Making it fast
Validated modules cached per release digest; instances reused within a job (T06); tiles or bands in parallel; buffer copies counted in the budget and minimized by the contract's buffer handles (T02); preview and final caches keyed separately (T13); deterministic output lets caches be reused across machines.
3. Seeing performance (Q1)
The Installed screen shows each plugin's recent cost ("used 38% of the last render", "slowest frame 210 ms") and memory. An optional overlay in the viewer shows per-plugin time for the current frame. Authors get the same numbers in craft-ext dev.
4. Offline, in one place
| Works offline | Needs a connection |
|---|---|
| Installed, set-up plugins; projects; placeholders; baking | Installing, updating, choosing another version |
| Browsing the cached catalogue (dated) | Fresh revocations (cached ones still apply) |
| Plugins' own private storage | Large resources not yet downloaded (T14) |
| No sign-in is ever required for public plugins | Plugins using network permission get a clear "offline" error they can handle |
5. Logs and support
- Per-app local log, size-capped and rotated; plugin lines marked with the plugin ID and treated as untrusted text; paths, URLs and document content redacted by default.
- Plugin authors log through the SDK; output appears in a Plugin console panel and in
craft-ext dev. - Create support report (explicit action): logs, installed plugin list with versions and digests, store state without secrets, app and OS version. The user sees the contents before saving; nothing is uploaded automatically and there is no crash telemetry.
6. Safe start (Q2)
- The app marks "loading plugins" at start and clears it once running. If the previous start did not clear it, the next start asks: "EffectCraft closed while loading plugins. Start with plugins off?"
- Also on demand:
--safe-mode, and Help ▸ Restart with plugins off. - Safe mode runs no plugin code and applies no plugin themes; the manager works for disabling or removing; projects open with placeholders and save their plugin data unchanged.
- "Find the problem plugin" (as VS Code's extension bisect): turns half the plugins off per restart until the culprit is found, then restores the rest.
T17 session proposal: ecosystem policy and long-term maintenance
Status: proposed 2026-11-10 after an all-perspective review (author refused a listing, author whose plugin broke on a new contract major, maintainer team of a few people, app maintainer wanting to change a shared contract, user of an abandoned plugin, bosses asking what this costs). Consolidates policy already settled and adds what is left. Not accepted.
1. Policy already settled
| Area | Settled |
|---|---|
| Store role | Lists only; binaries from authors' GitHub Releases; no building, hosting or responsibility (store role) |
| Licences | Store plugins MIT and/or Apache-2.0, bundled code and assets from the house allowlist; local installs any licence, labelled (T05) |
| Native | Allowed, labelled "Native: full access to your computer" (T06) |
| Checks | Bot always; quick human look for first listing, more permissions, new owner, native; 48-hour hold for auto-merged updates (T09, T10) |
| Official plugins | Same catalogue, same rules and licences, official flag set by maintainers only; rank first within a relevance tier (T11) |
| Proprietary or paid distribution | Not a store goal; no credential or entitlement integration |
2. Listing rules (Q2)
Refused or removed only for: malicious or deceptive behaviour; impersonation (names, icons or descriptions implying Storytold endorsement, reserved prefixes); illegal content; failing the bot checks; unverified namespace. Never refused for quality, for competing with a built-in feature, or for being native. Published as policy/listing-rules.md in the catalogue repository.
3. Decisions and appeals (Q3)
A refusal or block states the rule and evidence in the catalogue PR or issue. The author may appeal in the catalogue repository; a different maintainer decides, normally within 14 days. Emergency blocks stand during the appeal.
4. Contract support and deprecation (Q1)
- A contract major stays supported for a fixed period after its successor ships; apps keep both adapters during the overlap. Security-critical breaks may end support early with a published reason.
- Deprecations are announced in the generated contract changelog and shown to authors by
craft-ext checkas warnings; users see "this plugin uses an old interface and will stop working in after " only in the final months. - Contract changes go through a PR in craft-extensions; a shared domain contract change needs approval from maintainers of at least two apps that use it (T02 governance).
5. Ownership
| Part | Owner |
|---|---|
craft-extensions crates, SDK, craft-ext, conformance and benchmarks |
Platform maintainers |
| Each app's adapter, exported contract and its CI check | That app's maintainers |
| Catalogue repository, bot, keys, incidents | Catalogue maintainers (named when created, T09) |
| Shared domain contracts | Platform maintainers with the consuming apps' maintainers |
Names are for the bosses to assign; the design only requires that each part has one.
6. Documentation
Generated from the inventories: contract reference (docs.rs once crates are published, GitHub Pages until then), the contract changelog and compatibility tables. Hand-written: an author guide, one template per contribution kind (craft-ext create), small example plugins, the listing rules and the incident process.
7. Cost and scope
No servers: GitHub repositories, Actions and Pages. Ongoing cost is maintainer time (quick looks, incidents, appeals) and CI minutes (bot, benchmarks, conformance). Bot auto-merge keeps routine updates free of human time.
T18 session proposal: delivery and evidence
Status: proposed 2026-11-10. Orders the work that T01–T17 decided, without starting code. Replaces the draft implementation order where it assumed reusing existing app ABIs and a PhotoCraft-first slice, both superseded by the replacement direction. Not accepted.
Principles
- Platform pieces first, each small, tested and shippable on its own; then one app at a time.
- An app never has two plugin systems: its old system is removed in the same change set that lands its new adapter (Q2).
- No unit starts without its owner named (T17) and its part of the merge hold lifted.
Units in order
| # | Unit | Where | Depends on | Evidence before moving on |
|---|---|---|---|---|
| P0 | Accept the decisions, name owners, plan hold lifting per area | Maintainers | — | Owners named; this brief accepted |
| P1 | Store foundation: install enables nothing, per-app setup, grants record, leases, digest and source, read/write version numbers, user-chosen version change, manifest schema 2 (IDs, per-app contracts, permission families) | craft-ext-core, craft-ext-store | P0 | Crash at every step, concurrent writers, old reader still reads, update during a leased job |
| P2 | Operations kit: Invocation, principals, descriptor fields, authorize, errors, job model, exit codes |
New craft-extensions crate | P0 | Unit tests incl. denial before side effect, origin chain, management never exposed to plugins |
| P3 | Host runtime and hostile suite: one wasmi profile (PhotoCraft pattern), budgets, instance rules, failure contract | craft-ext-host, craft-ext-conformance | P0 | Hostile suite passes on every desktop target and web |
| P4 | First contract and SDK: inventory format and generator, raster.filter@1, craft-guest, macros, craft-ext create/check/test/pack/prepare-release/dev, reference host, example halftone |
craft-extensions | P2, P3 | Example plugin built, checked, tested and packed deterministically twice with the same digest |
| P5 | Shared manager component and plugin CLI commands (local file installs) |
craft-extensions | P1 | Install, setup, grant, version change, remove driven headless |
| P6 | EffectCraft pilot: dispatcher migrated to Invocation (caller, kinds, management split); attach over user-only socket and token; raster adapter with temporal basics; manager; placeholders and export refusal; old plugin crate, Plug-in Library and helpers removed |
EffectCraft | P1–P5 | GUI/CLI/MCP parity; export refuses a missing plugin; update during export; halftone runs; no open TCP port |
| P7 | Catalogue: repository (when maintainers create it), bot, TUF signing, 48-hour hold, revocation, client fetch using the download routine extracted from the launcher | New repository, craft-ext-store | P1, P4 | Swapped asset refused; expired metadata refused; revocation applied offline after one sync |
| P8 | FigCraft: session style (exposed operations, panels, tools, canvas, consent UI); APIs 1–4 removed | FigCraft | P6 | Panel/CLI parity; denied file operation; Escape cancels a tool unchanged; one undo step per edit |
| P9 | PhotoCraft: the same halftone module runs unchanged; old filter ABI removed | PhotoCraft | P6 | Identical output to EffectCraft for the same input (T02 promise) |
| P10 | Native plugins: out-of-process helper protocol and full-access label | craft-ext-host, EffectCraft first | P6 | A native effect crashes without affecting the app; revocation stops the process |
| P11 | Other apps by demand, each through the adapter checklist; FilmCraft temporal next; themes revisit | Each app | P6–P9 | Per-app proofs from the work packages |
| P12 | Public launch: catalogue live with keys held, listing rules, author guide, templates, examples, benchmarks setting budgets | All | P7, P8 | Community enablement decided by maintainers |
P1, P2 and P3 can run in parallel. P7 can run alongside P6 to P9; until it exists, pilots use labelled local file installs (Q3).
Evidence still missing (verify during the units, not before)
wasmi 2's accepted WebAssembly features for the SDK template (P3/P4); a maintained TUF Rust client and its licence (P7); budget numbers from benchmarks (P12); egui accessibility coverage for the manager and declarative UI (P5/P8); which app maintainers own each adapter (P0).
Merge hold
Each area of docs/plugins/merge-hold-list.md lifts when its unit lands; the EffectCraft plugin areas lift at P6 because P6 replaces them.
App adapters and standalone management (2026-11-10)
User direction: full plugin management must be available inside every app, so users never need the launcher, in launcher-installed and standalone installs and builds alike.
What an adapter is
One app adapter per app (not per plugin), in the app's repository. Every plugin used in that app goes through it. It connects the shared platform to that app and contains no copy of shared logic:
| Adapter part | Uses |
|---|---|
Contract export (xtask export-contract) and its CI check |
T03 |
| Implementations of the shared domain contracts the app offers (raster, temporal, …) and their conformance run | T02 |
Operation classification: kind, exposure, requires, management and core markers |
T04 |
| UI extension points: menu spots, panel docking, inspector sections, tool slots, canvas overlay | T12 |
| Project integration: saved references, placeholders, export refusal, bake | T13 |
| Jobs: render or export queue integration | T15 |
Management: embeds the shared manager component (Settings ▸ Extensions and an Extensions menu item) and wires the shared plugin CLI commands |
T11, T05 |
| Headless plugin-test entry for conformance | T03 |
Management without the launcher
- Each app links the same craft-extensions crates the launcher uses: store, catalogue client, download routine, manager component. Browse, install, set up, grant, version change, update and remove all work in the app and its CLI. No launcher, daemon or account is needed.
- One store for both: launcher and apps use the same shared folder (existing
location.rsrule,CRAFT_EXT_DIRoverride), so something installed in the app shows in the launcher and the other way round. The store lock and generation counter (T08) handle both being open at once. - The launcher adds only an all-apps view and deep links into an app's manager. Nothing is launcher-only.
Builds and packaging
| Build | Store |
|---|---|
| Standalone download (macOS, Windows, Linux tarball) | Shared folder |
| Launcher-installed | Shared folder |
Linux Flatpak (the launcher installs per-user Flatpaks, craft-launcher crates/native/src/packages.rs:16) |
The sandbox hides the shared folder by default. The Flatpak manifest grants access to that one folder only (--filesystem=xdg-data/<store folder>:create); if a distribution refuses that permission, the app uses its own store and the manager still works fully, without sharing |
| Web build | Browser-local store per app; install from file works; catalogue installs only if GitHub release downloads are reachable from a browser (cross-origin rules unverified) |
| Builds made without network code (offline products) | Manager with local file installs only, labelled; an advertised build choice, not another state format |
Appendix: per-app work packages
All rows inherit discovery/compatibility/activation/loading, caller policy, transactions, persistence, jobs, CLI/artifacts, errors, themes where supported and conformance fixtures from the full adapter checklist. “Gap” means an existing source-derived concern or an integration not established by the survey. “Design” names additional functionality to support, not functionality already implemented. Concrete code edits require the operation audit above.
| App | Expose through app-owned contracts | Known gap or required integration | App-specific proof |
|---|---|---|---|
| EffectCraft | Composition/layer/selection queries, keyframes and effect parameters, effect evaluation, frame dependencies, render jobs and artifacts | Fresh CLI loader differs from desktop; missing effects can be omitted; process registration/update and pooled state need explicit lifecycle; preserve existing WASM/helper semantics | Independent layer states, seek/reset, update during export, cancelled render, missing required effect prevents success |
| FigCraft | Node/selection queries, geometry/layout edits, components, commands/panels/tools/widgets, file artifacts | Headless clears offered-file UI requests; disk modules need integrity continuity; same-ID replacement/settings and permissions need integration | Same native result through menu/panel/CLI; denied nested/file operation; undo/stale handles/panel close |
| PhotoCraft | Pixel/layer/mask/selection operations, filters, smart features, colour-aware data, import/export and themes | Bridge existing band/filter ABI and theme branch; failed/missing smart filter can be skipped; fresh CLI and exact smart-feature references need work | Alpha/colour modes, overlap seams, selected regions, smart save/reopen, theme fallback and explicit output failure |
| FilmCraft | Timeline/clip/track/selection edits, transitions, media inspection, export jobs; later frame/audio processing | No processing plugin host established by sampled sources; design temporal interface and independent theme mapping; preserve existing job completion behavior | Timebase/frame dependencies, timeline undo, awaited export, playhead/selection/highlight/contrast preserved |
| VectorCraft | Object/geometry queries and edits, units, live appearances, format/export handlers and resources | Preserve distinct object/live-effect/export contracts; connect release/state/retention and cached appearance evaluation | Malformed geometry rejected; units preserved; live effect save/reopen; output artifact completed |
| SoundCraft | Routing/project edits, prepare/process/reset, instruments/MIDI/automation, latency/tail, preset/state and editor lifecycle | Existing native formats are not sandbox proof; dedicated real-time backend and worker-failure semantics required | Deadline/latency/tail evidence, transport discontinuity, state restore, worker failure without unsafe callback behavior |
| LightCraft | Catalog queries and scoped metadata/develop edits, RAW/develop context, presets and export jobs | Define catalogue access scopes and recipe/live references; protected DB access must remain behind app operations | Nondestructive reopen, missing source media, export cancellation and selected-item scope enforcement |
| PDFCraft | Page/object queries and edits, annotations/forms where app supports them, validation/preflight and output | Survey establishes facade/tool table, not a plugin object model; add scoped handles and transactional file/output path | Stale page/object rejection, history, preflight result and completed PDF write |
| DesignCraft | Stories/frames/pages/spreads/styles, layout/reflow, pointer tools, prepress and export | Move UI-bound behavior into engine where audit proves duplication; define gesture/reflow transactions | Cancelled gesture, reflow undo, units, invalid layout rejection and prepress artifact |
| CADCraft | Entity/model queries, units/constraints where supported, explicit-parameter commands and tools | Interactive prompts need headless parameter contracts or explicit UI-only designation | Missing prompt returns InputRequired, unit-correct edit, rollback and model save |
| SolidCraft | Candidate model/entity commands, feature/rebuild operations, geometry and saved procedural state | Existing manifest listing does not establish executable host; implement actual runtime/transaction path before claiming support | Real command invocation, validated model mutation, missing procedural feature preserved and failed rebuild reported |
| TextureCraft | Mesh/UV/texture-set/channel queries and edits, brushes/strokes, material/bake/composite jobs | Resource/mesh lifetime, stroke transaction and cache ownership need adapter integration | Wrong texture-set rejected, cancel stroke/bake, update during lazy resource use, UV invalidation |
| WordCraft | Durable text ranges, stories/styles, structure/layout edits, validators and output | Define positions that survive or explicitly invalidate across edits; no raw persistent string offsets | Concurrent insertion/stale-range handling, undo, layout and exported document |
| GridCraft | Typed range/cell/workbook operations, import/export; dedicated formula/function extension contract | Custom functions need recalculation graph, cycles/error propagation, deterministic evaluation and budgets | Range edit undo, cycle/timeout, type errors, recalc invalidation and workbook save |
| DeckCraft | Slides/shapes/text, transitions, assets, presentation/export jobs and optional playback callbacks | Playback subscriptions have a different lifetime from commands; connect saved state/output contracts | Shape save/reopen/export, stop callback disposal, stale slide target and cancelled export |
| ArtCraft | Media/model/provider jobs, input/output roles, progress/cancel/result ingestion and workflow resources | Native target/provider jobs established, but plugin host/common CLI not established; egress/credential scopes needed | Provider restart/cancel, no credential disclosure, remote/offline readiness and durable result ingestion |
Candidate operations do not authorize exposing every internal action. App maintainers choose the supported contract, and denied side effects remain denied even when a plugin invokes a compound operation through parameters.