Files
craft-extensions/docs/DESIGN-DECISIONS.md
arnav-hiwarkar b2ce37420f docs: apply the review answers
Record the answers to D1-D6, require an outside security review
before public launch and two maintainers for native releases, say that
native plugins are the exception to protection by design, and name the
maintainers as owners of the open setup items.
2026-11-10 18:46:16 +05:30

21 KiB
Raw Permalink Blame History

Design decisions

Status: record for review, 2026-11-10. Each row is a choice made in the plugin-architecture design sessions, in the order it was made, with the date and what it changed. The topic numbers (T01–T18) are the eighteen design topics. Later rows refine or override earlier ones; ARCHITECTURE.md is the consolidated result. None of these is accepted by the maintainers of this repository yet, and none authorizes implementation.

Where a row says "user", it means the person who led the design sessions; "designer" choices were delegated by them.

Topic Choice (date) Consequence Supersedes or refines
T01 grant unit Grants attach to the package within one app; each contribution is enabled separately (option B, 2026-11-08) One setup sheet per app showing the package's union of rights. Enablement controls what appears in the app and is not a security boundary. The runtime instance enforces authority. An update that widens rights asks again; a new contribution needing no new rights still starts disabled. Authors wanting stronger separation ship separate packages Refines "app-specific grants". Rejects per-contribution grants, which would need one enforced runtime instance per contribution because contributions sharing a module share memory
T02 contract structure Accepted the two-axis model (2026-11-08): interaction style (transform, session, data) and three contract layers (common mechanics, shared domain contracts, app contracts). A transform module written against a shared domain contract runs unchanged in every app whose adapter passes that contract's conformance suite; session contributions are always per app One reviewed module can serve several apps. Effective authority of an instance is its style's imports intersected with the package's grant in that app. Shared domain contracts (raster, temporal, audio, typed resources) are designed now; an app makes one available only after conformance passes; unforeseen needs start as app extensions and are promoted on a second consumer. Existing ABIs stay as legacy app profiles. Details in ARCHITECTURE.md section 6 Replaces the draft's "separate modules per app adapt the same algorithm" default for transforms
T03 SDK and author experience 2026-11-09, reopened: user chose A, every plugin-platform crate in craft-extensions, with app glue in app repos. Remaining selections stand as delegated on 2026-11-08. Originally: user delegated the remaining T03 choices to the designer (2026-11-08): "decide those things as per what's best for the application". Selected: all plugin-platform crates in craft-extensions; app registry export with breaking-change CI; committed generated guest crates whose major equals the contract major; contributions and parameters declared in Rust code and carried in a module custom section; one Craft.toml for identity and per-app permissions; author CLI named craft-ext; three test levels; isolated development store; deterministic release with previous-release comparison The proposal becomes the working design (ARCHITECTURE.md section 20). crates.io is the intended guest-crate distribution, but actual publication still needs explicit authorization at release time. Each app offering session contracts must provide a headless plugin-test entry. The wasmi-accepted WebAssembly feature set must be verified before the template is fixed Replaces the draft's hand-written author TOML listing contributions
T04 operation path User accepted the whole T04 system (2026-11-09): one execute(invocation, op, args) path with the caller-less signature removed; exposure, then resolved-argument authorization, then availability as a UI hint only; authority-changing settings split into management operations never exposed to plugins; typed schemas generating SDK, CLI, MCP and docs; dispatcher-owned transactions with origin-labelled undo and post-commit outbox effects; handles and captured scope; short commands and revision-checked jobs; origin recorded in journal, learning, logs and replay; post-commit events; load-time operation resolution; stepwise per-app migration with shared types in craft-extensions T04 proposal and revision
T04 automation authority User chose A (2026-11-09), "as long as CLI has full access and plugins are safe". A CLI command the user runs directly is the user, with full authority including management. Clients attached to a running app (MCP, control channel, attached CLI) get the user's full document authority; management operations (install, enable, grant, script/automation permissions, update sources) need a management scope the user approves in the app, once per session Plugins never reach an automation channel: no socket import, any future network grant excludes loopback, channel tokens never given to plugins. Channel authentication details in T15
Open ecosystem direction User direction (2026-11-09): plugins may use the CLI and its tools and the community must not be restricted in what it builds; plugins cannot change built-in (main) features; plugins are free and open source; every plugin accepted into the store must be reviewed as safe and not malicious; store plugins are MIT or Apache-2.0 licensed Changes T04 plugin exposure from opt-in per operation to: every operation exposed to the CLI or automation is available to plugins, except management and protected-core operations. "Use the CLI" means calling the same operations in process through the dispatcher, not launching processes. Store admission (corrected 2026-11-09): the store only lists plugins; it does not build, host or take responsibility for them. Binaries come from the author's GitHub Releases. Admission is a check that the package conforms to Craft formats and rules plus a light test, not a safety guarantee; the catalogue pins the reviewed asset digest. Supersedes the open licence row and the proprietary/restricted-release design requirement for the store. Local-install and dependency-licence treatment asked as T05 questions
T05 permission vocabulary and licences User accepted (2026-11-09): plugins call CLI/MCP operations in process, never by launching processes; permissions are shared families (document, files, network, account, clipboard) with access and scope; store plugins MIT and/or Apache-2.0 with bundled dependencies and assets from the house licence allowlist; file installs outside the store allowed with any licence under the same sandbox and permissions, labelled "Not reviewed" T05 proposal and open-ecosystem direction. The dependency-licence choice was accepted as the recommendation without being named
T05 consent moments User chose A and A (2026-11-09): optional permissions are asked at first use, only from a user-started GUI action, in a host-drawn prompt; CLI, agents and renders never prompt. A CLI the user runs directly may grant and revoke through separate plugin grant/revoke commands, never as a flag on execution commands; attached agents need the in-app management scope Closes the CLI grant-management row in remaining decisions
T06 runtime and safety User chose (2026-11-09): Q1 A, one shared wasmi profile from PhotoCraft's pattern (deadline-sliced fuel, total memory, strict limits) with an engine-neutral host, a JIT engine only after measurement; Q2 C, native plugins (helpers, OpenFX/VST-style hosts) allowed in the store after review; Q3 A, a plugin failure during final render or export fails it Native plugins (corrected 2026-11-09 by the user): listed like any other plugin, binaries from the author's GitHub Releases, light review only; they may do anything the user's account can. Kept: out-of-process helper protocol (crash containment), a distinct "Native: full access to your computer" label and consent, pinned asset digests and delisting/revocation. Dropped: store-built binaries, two-reviewer and full review, OS confinement as a store requirement (remains an optional future runtime improvement). Transform instances reused only within one document and job Updates the earlier backend table, which kept native workers out of the safe path
Store role User corrected (2026-11-09): the store lists plugins only; binaries come from authors' GitHub Releases; no building, hosting or responsibility; a light conformance check and test before listing. User chose A: WebAssembly plugins keep the T05/T06 sandbox and permissions, native plugins are the full-access route Kept: pinned asset digest in the catalogue record, bot checks (manifest, MIT/Apache licence file, source link, digest, load and smoke test), labels ("Native: full access to your computer", "Not reviewed"), delisting and digest revocation Supersedes store rebuild and per-release human review
T07 identity and compatibility User accepted (2026-11-09): package IDs stay reverse-domain (io.github.<owner>.<name> verified against the GitHub repository owner; other domains verified once by a maintainer; first-party prefixes reserved), no UUID; contribution ID <package>/<contribution>; release = ID + version + pinned asset digest; ownership transfers recorded and shown as "has a new owner" with confirmation before the next update; compatibility decided by per-app contract major/minor, app version optional; outcomes compatible, partly compatible per contribution, incompatible with the update to make; projects save contribution ID, exact version, contract version, parameters and versioned state; legacy IDs claimable only within the package's own namespace T07 proposal. Replaces pkg:<uuid>/<contribution> in earlier drafts
T08 store and lifecycle User chose (2026-11-09): Q1 A, a running app picks up an update at the next safe point (transforms on next use, session contributions when idle with a notice) and running exports and jobs finish on the old release through leases; Q2 B, keep only the current release plus any still leased, and the user may choose any listed version to download, older ones included (an explicit user-chosen version change replaces the blanket downgrade refusal; no offline rollback); Q3 B, always ask before every update Store keeps: five state kinds with one owner each (release bytes, package record, per-app setup, leases, caches), install enables nothing, update beside the old release, crash-safe transitions, SQLite-style read/write version numbers for state. T08 proposal
T09 distribution and catalogue User chose (2026-11-09): Q1 A, the bot merges routine updates (checks pass, no new permissions, same owner, not native); first listings, wider permissions, owner changes and native plugins get a quick human look. Q2: a new metadata-only catalogue repository stays planned, its name, owner and maintainers left to maintainers Path: author GitHub Release, catalogue PR with releases/<version>.toml, secret-less bot checks, signed catalogue.json, client download from the author's URL with pinned digest. Records keep numeric GitHub owner and repository IDs to detect renames and repo-jacking; deleted upstream releases are not mirrored; EffectCraft's effectcraft-plugins index folds into the one catalogue. T09 proposal Creating the repository needs maintainer authorization
T10 authenticity and incidents User accepted (2026-11-09): catalogue metadata signed with TUF through an existing Rust client (licence and maintenance to verify), trust root in the signed app, online key only in a protected publish job, offline root keys 2-of-3 on hardware keys with a rehearsed recovery; auto-merged updates held 48 hours before reaching users Revocation by exact digest (also matches file installs), package version range or publisher; severities advisory, block new, disable (running work stops at next host call, native process killed, export in progress fails); any maintainer issues, disable reviewed by a second within a day; apps check at start and every few hours; project data never deleted. T10 proposal Key holders named when the catalogue repository is created
T11 search and management UX User chose A and A (2026-11-10): official plugins rank first within each relevance tier only; when a built-in search finds nothing the app suggests matching plugins from the cached catalogue, without sending the query anywhere, with a setting to turn it off One shared egui manager component in craft-extensions shown in every app (that app only) and the launcher (all apps), with CLI parity; Browse, Detail, Install and setup, Installed, Updates and Problems screens; stars fetched centrally. T11 proposal
Replace existing app plugin systems User direction (2026-11-10): ignore the plugin systems the apps have today; they will be removed completely and replaced by this design Supersedes in T02 "existing ABIs stay as legacy app profiles", the T05 migration table, T07 legacy_ids and EffectCraft index folding in T09. Old projects referencing removed plugins open with data-preserving placeholders. Existing code is lessons, not constraints. Removal happens app by app as the new system lands (T18)
T12 plugin UI User chose A, A, A (2026-11-10): host-drawn declarative UI (panels, dialogs, inspector sections, settings pages) with a custom canvas element taking draw lists or an image; suggested default shortcuts only when the chord is free, never replacing built-in or user bindings; menu items in declared extension points of the real menus, appended after built-ins and grouped by plugin No webviews (house rule). Events run off the UI thread under the command budget; one undo step per edit; Escape cancels tools unchanged; UI contributions absent headless; unlabeled controls refused by the SDK. T12 proposal
T13 projects and output User chose (2026-11-10): Q1 A, a newer compatible release is used with a quiet note; Q2 A, "Bake plugin result" converts output to app data and keeps the original switched off; Q3 B with default off, projects may carry plugin files through an explicit "include plugins" option Carried plugins are never installed or run on open; "Install from project" is an ordinary file install (validation, digest matched against the catalogue, otherwise "Not reviewed", revocation by digest, normal setup and permissions). Projects store contribution ID, exact version, contract version, parameters, versioned state and a project-level plugin list, never grants; placeholders keep all data byte for byte; final render and export refuse to start with any missing, failed or blocked plugin; preview and final cached separately. T13 proposal
T14 resources, themes and workflows User chose (2026-11-10): Q1 A, a workflow runs as its package with the permissions it declares, approved at setup; Q2 A plus a setup offer, large referenced files (URL, size, SHA-256) are offered at setup with "Download now" (primary) or "When first needed", and otherwise download on first use with the size shown; Q3 A for now, themes change colours, fonts and density only Every data kind has one bounded importer and installation runs nothing; translation packs never replace permission, consent or warning text; large files resumable, digest-checked, content-addressed and shared between packages. Themes to be revisited later at the user's request. T14 proposal
T15 automation and jobs User chose A, A, A (2026-11-10): attach through a user-only Unix domain socket or user-restricted named pipe plus a per-session token, with no network port by default (remote server mode later, explicit, TLS and token); a " is controlling · Stop" banner while any external client is connected; attached jobs continue after the client disconnects and can be rejoined by ID Fresh CLI, attached and server environments share operations, results and error codes; a fresh CLI refuses to write a project open in a running app; one job model with progress and cancel (CLI, MCP notifications, jobs commands); outputs written to a temporary name and renamed when complete; exit codes 0 done, 1 failed, 2 usage, 3 input required, 4 plugin missing or not permitted, 5 cancelled. Replaces today's unauthenticated localhost TCP control ports. T15 proposal
T16 performance, offline, diagnostics User chose A and A (2026-11-10): per-plugin cost and memory shown in the manager with an optional viewer overlay; safe start offered automatically after an unfinished start, plus --safe-mode, Help ▸ Restart with plugins off and a bisect "Find the problem plugin" Budgets from a CI benchmark set on reference hardware with generous headroom; app-wide plugin memory ceiling; interactive and preview outrank export; engine re-evaluation trigger tied to 4K reference effects; offline table; local rotated redacted logs, Plugin console, user-reviewed support report, no automatic upload or crash telemetry. T16 proposal
T17 ecosystem policy User chose A, A, A (2026-11-10): an old contract major stays supported 12 months after its successor ships (earlier only for published security reasons); listings are refused or removed only for malicious or deceptive behaviour, impersonation, illegal content, failed bot checks or unverified namespace, never for quality, competing with built-ins or being native; appeals in the catalogue repository are decided by a different maintainer, normally within 14 days, with emergency blocks standing meanwhile Shared contract changes need approval from maintainers of at least two consuming apps; one owner per part (platform, each app adapter, catalogue), names assigned by maintainers; generated contract docs plus author guide, templates and examples; no servers. T17 proposal
T18 delivery User chose A, A, A (2026-11-10): units P0–P12 in order (owners; store foundation, operations kit and runtime in parallel; first contract and SDK; manager and CLI; EffectCraft pilot; catalogue alongside; FigCraft; PhotoCraft running the same module unchanged; native protocol; other apps; public launch); each app's old plugin system removed in the same change set as its new adapter; labelled local file installs for pilots until the catalogue exists Merge hold lifts area by area as units land. Evidence still to verify during the units: wasmi feature set, TUF Rust client, benchmark budgets, egui accessibility, adapter owners. T18 proposal
In-app management and app adapters User direction (2026-11-10): full plugin management inside every app, so the launcher is never required, for launcher-installed and standalone installs and builds One adapter per app in its repository (contract export, domain contract implementations, operation classification, UI extension points, project and job integration, embedded shared manager and plugin CLI wiring, headless test entry); apps link the same store, catalogue client, download routine and manager component as the launcher; one shared store folder so both see the same installs; Linux Flatpaks grant access to that one folder, else use their own store; web builds use a browser-local store. Adapters and standalone management Confirms T11's shared component. Web catalogue downloads need a cross-origin check
Gap-check answers User chose (2026-11-10): catalogue repository on GitHub with the signed catalogue served as static files from our own domain and GitHub Pages as backup (no private servers, no file mirror); plugins may define new document object types, host-managed with a saved fallback preview; packages may depend on data packages by ID and version range, with plugin-to-plugin calls later; app scripts and expressions stay app features and script plugins come later; no account sign-ins in the first release; setups export and import between computers with permissions asked again; old plugin systems just removed with release notes; internal security review only before launch; a short disclaimer, takedowns case by case; SoundCraft VST3/CLAP/AU hosting and CADCraft AutoLISP kept as native full-access mechanisms in the shared manager, with AutoLISP no longer able to redefine built-in commands Also added to the architecture without new choices: default handlers for duplicate formats, development-store packages treated as Not reviewed, tier-to-label mapping, clock-rollback handling, network rules, private storage, restart-only unload as adapter work. Architecture Narrows "replace existing app plugin systems": the two industry-format hosts stay
App adapter design User chose the recommendations (2026-11-10): adapter levels L0 (manager, store, CLI, data add-ons), L1 (transforms), L2 (session plugins), with every app shipping L0 early; shared traits in craft-ext-host and one adapter crate per app with a generated skeleton and a checklist test; CI fails for any operation without a plugin marking; the platform team builds the EffectCraft, FigCraft and PhotoCraft adapters with those maintainers, then each other app's maintainers build and own theirs Adds delivery unit P5b (L0 in every app). Architecture section 21
Maintainer review of the architecture Jeremy8776 approved storytold/craft-extensions#1 (2026-11-10) and answered the six conflicts; the user accepted his two changes: an independent outside security review of the platform before public launch (P12), replacing the internal-only choice, and two maintainers approving every native listing and release (G10, native only). Also agreed: open store as the target with the third-party feature off until P7; permissions as declared, host-granted, generation-checked (G6); transform plugins only until P2; no store builds, source link and pinned digest required; stars without telemetry; EffectCraft, FigCraft, PhotoCraft Next: a docs PR updating THREAT-MODEL.md and the README, then store changes C1, C2 and C4 with failing-first tests Replaces "internal security review only" and the single quick look for native