stillmade-sdk 0.1.4 → 0.1.6

package/NATIVE_APPLICATION_ADAPTATION.md

@@ -0,0 +1,565 @@
+# Native applications within a universal Block system
+
+## Native adapter authoring contract — September 30 continuation
+
+Create now prepares source-backed native adapter drafts through a bounded LLM
+service after preferred browser routes. On supported installed desktops, Create
+now connects managed setup, a real isolated CMake build and bounded evidence-driven
+repair. Application installation and admission remain unavailable until the
+independent runtime review path is implemented. See
+`../../artifacts/repository-acceptance/github-native-authoring-2026-09-30/README.md`
+for actual trials, rejected replies, costs and verification boundaries.
+
+The user-authorized application importer uses exact GPT-5 mini through the
+trusted provider adapter at $0.25/million input and $2/million output tokens.
+Native turns allow up to 8192 completion tokens including reasoning; browser turns
+remain 4096. Model response formatting is guidance, never admission. The backend
+retains worst-case dispatch reservations and enforces account/global/source money
+limits across the old and new model history. Desktop HTTP authoring additionally
+fences canonical account/source lifetimes to nine turns without client reset IDs;
+reserved/unknown dispatches block further calls. Confirmed, trusted, metered
+truncation can request a bounded revision without losing incurred expense.
+
+The base local builder verifies pinned complete source and submodules, root-sealed
+host helpers, toolchain identity, offline systemd isolation, observed cgroup limits,
+independently frozen artifact capture, and empty cgroup teardown. A real cJSON
+build is retained in `native-cmake-cjson-r8/result.json` under the linked acceptance
+folder. This proves compilation and capture only. Existing Qt/native application
+requirements, adapter materialization, application behavior, native admission,
+multiplayer and connected export still need actual integration and verification.
+
+The implemented Python lifecycle API is `NativeAdapter` from `native_adapter`
+(`packages/block-sdk/native_adapter.py`). Import this class; do not redefine it.
+Register `{ 'checkpoint': handler, 'execute': handler }`, retain the adapter and
+event-loop timer, and call `poll()` from the actual application event loop.
+Handlers receive one payload dictionary and must return the boolean `True` only
+after the real save/export completes. Copying an old project file or writing a
+simulated output cannot establish persistence or export.
+
+The launch request must load the adapter: either launch the declared adapter
+entrypoint or pass its declared relative path through the application's inspected
+startup hook. An unused file cannot implement lifecycle handlers. A launcher
+entrypoint must actually start the original application; referencing its own name
+alone does not establish that behavior. Implicit startup-file mechanisms require
+application-owned launcher glue and independent execution verification.
+
+`execute` receives exactly one payload dictionary. `operation` is a string ID,
+and `stateRevision` is a string. `outputFiles` is an array of
+`{port,path,mimeType}` entries. Each supplied path is a fresh relative
+`.stillmade-exports/<executionId>/...` location below `/work`; use that request's
+path rather than overwriting a saved document or reusing a template output.
+
+`documentPaths` and build artifacts are arrays of literal relative path strings,
+never globs or descriptor objects. Export operations are exactly
+`{id, files: [{port, path, mimeType}]}`; typed ports belong at the top level.
+`testInput` maps scalar/JSON port names directly to values, without invented
+media references. State guidance is prose, not an unvalidated state document.
+Each operation must capture its declared outputs without aliasing saved documents.
+Build/dependency/launch declarations are requests for independently verified host
+support, never authority to run installers or host commands.
+
+Source citations must identify actually inspected, Git-verified bytes. The host
+may inspect known unread files cited by a candidate within the same cumulative
+source budget, then request a revised declaration. Invalid/unknown/out-of-scope
+paths never gain access. Initial API discovery and symbol/line summaries are
+generic heuristics and do not prove feature parity or callable ABI compatibility.
+
+JSON formatting does not establish conformance. The host validates every reply
+and retains incomplete source/feature/runtime evidence explicitly. Unknown model
+dispatch stops retries. A fully received, independently metered truncated reply
+retains its maximum reservation and records its expense before a bounded shorter
+revision; copied or model-supplied expense claims cannot authorize that revision.
+
+Native authoring requests a host-registered JSON Schema using a process-local
+handle, not provider parameters supplied by source or a client. The response is
+exactly one of `{plan:{...}}`, `{inspect:[...]}` or `{findPaths:{...}}`.
+Formatting schemas have a bounded context allowance included before reservation.
+Provider-side grammar bounds may be simpler than host bounds; all source, size,
+type and lifecycle checks still apply independently. The live cheap-model trials
+demonstrate that a well-shaped plan can contain fabricated application code.
+Such drafts remain unbuilt, uninstalled and unverified.
+
+Runtime direction and isolated development proof, updated 2026-09-30. A bounded
+offline native **compute** profile, source preflight, experimental native GUI
+supervisor and shared host draft lifecycle are implemented and locally tested.
+Automatic native installation and full application import remain **unimplemented**.
+Use with GITHUB_APPLICATIONS.md, DESKTOP_EXECUTION.md, WORKSPACE_SYNC.md and
+BROWSER_APPLICATIONS.md. Existing releases and host adapters remain intact.
+
+## One contract, several execution environments
+
+StillMade should own one project/workflow contract above interchangeable,
+versioned execution profiles: isolated JS/recipes, browser applications, native
+compute jobs, native interactive sessions, and trusted external capabilities.
+The LLM writes repository-owned adapters; it does not implement security policy
+or invent an executable grant. A profile is a host implementation, not a string
+that makes arbitrary code supported.
+
+Separate two decisions: **where the engine runs** (device or hosted worker) and
+**how the interface is presented** (Block-owned web UI or native UI stream).
+Natron can preserve its Qt interface in an isolated native session while
+StillMade presents that session inside the Block. A generated web control panel
+can offer common operations, but it is not full-interface parity. A renderer-only
+job is useful and remains explicitly distinct from an application import.
+
+The browser cannot directly load the native desktop executable and its OS,
+Python, OpenFX and graphics dependencies. Qt supports WebAssembly, but a port
+requires a compatible build and dependency closure; native plugins do not become
+browser plugins automatically. Do not classify C++ itself as impossible in a
+browser. See https://doc.qt.io/qt-6/wasm.html .
+
+For a broad native family, evaluate an isolated Linux VM/worker first, with an
+optional display server and authenticated display/input channel. Start with CPU
+software rendering. A container alone is not the complete isolation policy for
+hostile repositories. OS-specific binaries and GPU workloads need separate
+profiles. Do not assume Firecracker provides a GPU or a remote desktop: those
+are separate choices. No hosting purchase, worker deployment or paid compute is
+authorized by this proposal.
+
+## Runtime adapter boundary
+
+Use the existing execution envelope/receipt design; do not add a second Revolver.
+Each profile must implement a common lifecycle equivalent to prepare, open,
+applyInputs, execute, checkpoint, restore, cancel and dispose. These names are a
+proposed common interface, not new callable SDK APIs.
+
+The host supplies exact package/source/build/dependency/profile identities,
+project and placement scope, an input/state revision, scoped artifact handles,
+operation, timeout, resource ceilings, and budget authorization where relevant.
+The guest returns progress, checkpoint candidates and output candidates. The
+host independently validates/materializes output and issues the accepted
+receipt; repository code cannot mint proof or expose credentials.
+
+Typed ports and semantic compatibility remain in the current resolver. Media
+moves between runtimes as durable content/version-bound host assets, not guest
+paths, screenshots or temporary URLs. A video preview is separate from a
+completed typed video output. Changed inputs/state, revocation and cancelled
+runs invalidate late publication.
+
+A native rendering success does not automatically qualify existing rendering
+bridges for migration. Browser, native, ComfyUI and provider-backed execution can
+share the outer lifecycle while retaining their current executors and trusted
+billing/approval boundaries. Migrate behind adapters incrementally and preserve
+saved releases, installed pins and output meanings.
+
+## Scope and reusable adaptation procedure
+
+1. Pin repository, submodules, dependencies and build image; inspect source and
+   licenses as untrusted data. Inventory the actual application and establish
+   an independent representative baseline.
+2. Check a browser build first, including existing web interfaces and feasible
+   WebAssembly ports. Detect dependencies and choose an **implemented** profile.
+   Root build clues now produce browser candidates or native requirements in
+   the existing inspection response. They never set `desktopOnly:true` or
+   authorize installation. No LLM call is needed for this bounded evidence
+   check; it is not a build test or complete static analysis.
+3. Write a Block-owned adapter against the app's genuine document/operation APIs.
+   Build in a disposable worker without credentials or unrestricted host mounts.
+   Map dependencies and output artifacts explicitly.
+4. Map editable state: native documents plus asset closure, schema version,
+   migrations, checkpoints and authority over the current revision. Arbitrary
+   XML/binary project files cannot be made collaborative by generic JSON merging.
+5. Prove one producer → application → consumer, save/reopen, two placements,
+   pending-edit/stale result rejection, cancellation, revocation and failure.
+6. Test hostile filesystem/network/process requests and CPU, memory, scratch
+   disk, time and concurrency limits. Verify bounds during execution, not only
+   after output is produced. Price/reserve aggregate paid execution in the host.
+7. Admit only the exact tested artifact/profile. Reports and fixtures are never
+   execution evidence. Return precise missing support when a gate fails.
+
+### Dependency closure and behavioral repair
+
+A successfully linked application is not a complete application. Inspect runtime
+plugin discovery, optional build features, dynamically loaded modules, data files,
+color configurations and document asset references. Record which features were
+actually compiled and exercise the features promised by the imported application.
+Do not silently disable missing dependencies to obtain a smaller passing build.
+A deliberately partial development build must remain an unadmitted probe.
+
+Plugin lookup names can disagree with the executable's architecture. The pinned
+Natron OpenFX host, for example, chooses a Linux lookup folder from pointer width.
+An AArch64 plugin can require the legacy `Linux-x86-64` folder label. Derive this
+from the pinned loader source and inspect the real binary architecture; a folder
+name must never authorize cross-architecture execution or an emulation runtime.
+Keep layout adjustments in the package adapter, not a per-application host branch.
+
+Separate build, discovery, factory creation, operation, artifact capture and
+semantic validation. Each can fail after the preceding stage succeeds. A void
+render call or an adapter's `completed` response does not prove a file was written.
+Missing or invalid artifacts fail the operation before publication or downstream
+handoff. Preserve bounded diagnostics and the real application interface when
+possible, so repair uses the observed failure rather than guessing from metadata.
+Diagnostics and repository text remain untrusted model context and confer no
+permission, runtime admission or output authority.
+
+Use different resource profiles for building and interactive application use.
+Do not expand an interactive session's lifetime, scratch or output allowance to
+accommodate a compiler. Dependency provisioning is a trusted host operation;
+repository recipes and generated requests cannot choose arbitrary root installers.
+Managed setup also needs a live storage check and actionable recovery. A transient
+storage failure is not evidence that a repository itself is incompatible.
+
+For multiplayer, either map application operations to a shared host document
+with tested conflict semantics, or implement a host-enforced exclusive editor
+lease with viewers, expiry, takeover, checkpoints and recovery. The latter can
+be an honest initial collaborative mode, but it is not simultaneous editing and
+is not available just by declaring it. Current Natron shared controls/project IDs
+do not establish shared native project content across devices.
+
+## Implemented development proof
+
+`scripts/native-worker` implements `linux-native-offline/1` in a separate local
+Linux VM with no host mounts. A root-owned supervisor starts each operation as
+a fresh unprivileged systemd job. One job runs at a time. Fixed policy denies
+network and host credentials and enforces 100% CPU, 512 MiB memory, no swap,
+64 tasks, 96 MiB total temporary filesystems, and a 60-second wall limit.
+Repository code cannot provide process options or change those limits.
+
+`native-application.js` and `native-application-execution.js` validate bounded
+content-hashed packages, scalar typed ports and exact execution/state receipts.
+The trusted host checks permission before dispatch and publication, retains
+private completion records, serializes placement state, rejects replay and
+rejects retained outputs after the current state changes. The existing
+experimental planner/segment-runner boundary carries these operations; there
+is no new Revolver or per-engine execution branch.
+
+The unrelated BSD-licensed `blocks/repository/inih` compiles its pinned upstream
+C parser inside this worker and passes genuine output to a connected consumer.
+Real acceptance covers save/reopen, a second run using committed state, two
+isolated placements and stale-output rejection. Hostile probes cover filesystem
+and network denial, scratch exhaustion, memory exhaustion, timeout, cancellation
+and descendant cleanup. See `artifacts/repository-acceptance/native-inih`.
+
+This is **development-only**, not public admission. The VM's base system is
+readable, and its trusted supervisor is outside the job sandbox; the physical
+host's files are not mounted. Supervisor source hashes are checked, but the
+entire runtime/dependency image is not yet an immutable release. Provisioning
+uses distribution packages and must become a verified runtime artifact before
+shipping. Crash-lock reconciliation, retained-result garbage collection,
+distributed leases, GUI sessions and media materialization remain missing.
+Ambiguous completion blocks retry. No paid capabilities or spending authority
+are exposed. Generic SDK installation still rejects this experimental runtime.
+
+This library proof does not claim inih cannot run in a browser. It deliberately
+tests native portability without teaching the host a particular repository.
+
+## Next proof, kept small
+
+Move Natron behind this package-owned compute boundary after adding a trusted
+media materializer and a verified build for the worker architecture. Its
+existing macOS rendering bridge is tested separately and has weaker resource
+limits; it is not migrated by this work. Then add an optional native UI stream
+and tested editing-lease/checkpoint path. GPU support follows measured need.
+Existing provider and browser Blocks retain their executors during migration.
+
+The most universal product is a browser-accessible StillMade host with optional
+local and hosted workers behind this contract. Desktop/local execution can avoid
+hosted compute expense; hosted execution can reach devices unable to run the
+engine. Neither location guarantees arbitrary OS/GPU/plugin compatibility or
+nontechnical usability of the original native interface.
+
+## Local setup and download experience
+
+Prefer a proven browser route. If only a tested desktop profile is available,
+show **Desktop only**, explain what it does and offer **Set up on this device**.
+Show download size, required disk space and supported devices before setup.
+The user should not install compilers, Qt, Python or plugins individually.
+
+Use one app-managed StillMade data root (normally the OS application-data
+folder), with `runtimes`, `blocks`, `projects` and `cache` underneath. Provide
+Open folder, Repair and Remove downloaded files controls. Never delete saved
+projects when clearing runtime downloads. Reuse exact compatible runtimes
+between Blocks, and retain versions needed by saved projects.
+
+Setup must verify host-approved hashes/signatures, dependency closure and
+platform compatibility; extract safely; install atomically; probe isolation;
+and enable only the exact admitted runtime. Use the existing dependency-store
+machinery rather than letting an LLM invent download URLs or execute installers.
+That machinery does not yet provide this complete activation flow. The proof
+uses a separate developer VM, not the final managed StillMade folder layout.
+
+Execute locally by default with no automatic cloud fallback or provider calls.
+Cloud hosting is a future opt-in only when explicitly justified and authorized.
+Local execution still uses the user's storage, CPU and memory. A phone/browser
+without an eligible local worker should explain the desktop requirement, not
+silently rent a server. Shared project state and Revolver port contracts remain
+the same; live native-session ownership still requires the missing lease work.
+
+## New source-preflight helper
+
+`packages/block-sdk/repository-runtime-preflight.js` exports
+`repositoryRuntimePreflight(source)` and `NATIVE_APPLICATION_SUPPORT_GATES`.
+The server passes blob-verified source from the same cumulative-budget inspector.
+It reads at most six root build files / 128 KiB; nested dependency/example build
+files do not independently classify the application. It returns source identity,
+Git blob/SHA-256/line evidence, reasons and next actions, always
+`installable:false`, `execution:'not-run'`, `inventoryComplete:false`.
+
+A miss means further inspection, never browser compatibility. Conditional build
+branches may match and need deeper analysis. A hit does not reject alternative
+verified ports forever. Neither this helper nor its host gate checklist executes
+or authorizes anything. No runtime is granted by repository/model declarations.
+
+This additive guide/helper is staged for integration with the active SDK work.
+It has not been added to published/downloaded SDK archives or deployed docs.
+
+
+## September 30 interactive development evidence
+
+`scripts/native-session` now implements a separate experimental
+`linux-native-interactive-offline/1` supervisor primitive. It is not a supported
+installation runtime. See its README and the September 30 section of
+`GITHUB_APPLICATION_AUTHORING_2026-09-28.md` for live evidence and remaining
+product requirements. The original Natron UI now accepts real input in an
+isolated session, and native document edits survive a fresh-session restore.
+
+Reusable guidance for authors and runtime implementers:
+
+- Specify the native document and asset closure, not just UI screenshots or
+  scalar settings. Verify a UI edit changes serialized application state, then
+  restore and edit it again to disprove copied/fixed output. A candidate
+  checkpoint is not an accepted typed output or multiplayer commit.
+- Native account lookups need scoped OS metadata even when there are no user
+  credentials. Supply that metadata independently in the host profile; do not
+  expose userdb/system-bus authority or weaken isolation to obtain a name.
+- Native interface preservation includes popup focus and mouse gestures. A
+  framebuffer alone is insufficient. Any trusted window manager must disable
+  command-launching/autostart paths accessible to untrusted application input.
+- Keep application and trusted display/helper identities separate. Authoring
+  code cannot select systemd properties, mounts, credentials or resource limits.
+- Reobserve transient process-group errors during cleanup. Unreadable
+  observations do not prove termination, and an unresolved fence cannot be
+  cleared or retried by the repository adapter.
+
+This guide adds no callable permission or runtime grant. The existing outer
+Block contracts and admission checks still apply. Native media export, managed
+setup, actual app installation, multiplayer and Revolver acceptance remain
+unverified for this interactive prototype.
+## Shared host lifecycle and native checkpoints — September 30
+
+Native and browser sessions now reuse
+`desktop/application-session-authority.js` for permission checks, bounded
+operations, cancellation, late transport disposal and termination quarantine.
+The experimental native draft controller uses the same host revision-store
+interface as the browser controller, rather than a separate native workflow.
+Its exact bindings include package, application, runtime and input identities,
+with project/placement separation and application/runtime-bound restore bytes.
+This is trusted host code, **not an adapter capability or runtime admission**.
+Repository code must not import or supply its authority/transport callbacks.
+
+Native checkpointing must capture all declared document files under one freeze,
+retain that freeze through revision acceptance and resume only the exact named
+checkpoint. Permission loss or conflicting state must stop the session. The
+supervisor implements that protocol for one to eight files, with a 4 MiB total
+decoded byte cap; the draft controller also caps encoded JSON at 4 MiB. Larger
+projects need scoped host artifact storage, not an unbounded state payload.
+Snapshot capture does not flush dirty UI state: adapters still need a bounded
+native-save handshake, verified against the real application's saved result.
+
+A live Natron test uses this shared lifecycle for actual UI edits, save/reopen,
+revocation hooks and conflicting-save termination. See
+`artifacts/repository-acceptance/natron-native-draft-2026-09-30`. It is a manual
+development adapter and persistent local fixture store, not server permission,
+multiplayer, installation, automatic authoring or Revolver/export acceptance.
+No source/runtime gate was relaxed and no native output receipt was issued.
+
+The live conflict test exposed frozen-unit shutdown failure. Explicitly thawing
+the fenced application before stopping its units fixes that case; empty-cgroup
+confirmation still controls fence release. Automatic reconciliation after a
+supervisor crash remains missing and must verify owner/session identity and all
+descendants before allowing another session. Existing root-private locks must
+never be cleared just because an observation or operation timed out.
+## Native adapter save handshake — September 30
+
+The experimental GUI supervisor now provides a private, read-only mounted
+control directory at `/run/stillmade-adapter`. This is an application protocol,
+not a privileged SDK service or normal import/runtime grant. The SDK archive
+includes `packages/block-sdk/native_adapter.py` as unprivileged adapter source.
+Ship the exact helper as `native_adapter.py` in the sealed application package.
+Equivalent handlers can use this JSON/Unix-socket wire in another language;
+Python and Qt are not requirements of the host channel.
+
+Register application-owned handlers and call `NativeAdapter.poll()` from the
+application's own event loop. GUI API calls must run on the correct GUI thread.
+A Qt adapter can keep a `QTimer` and adapter instance alive for the session,
+connect the timer to `poll`, and provide a `checkpoint` handler that saves the
+live application document to the declared paths under `/work`. Return `True`
+only after the actual save succeeds. Missing handlers, explicit failures and
+acknowledgement timeouts stop the host operation; there is no fallback that
+silently captures old files as a successful save.
+
+`context.json` supplies schema version 1, protocol
+`stillmade.native.adapter/1`, session ID and sealed application SHA-256. Each
+host `request.json` contains schema version, those exact identities, a fresh
+request UUID, action and bounded JSON payload. The current save payload is
+`{"documentPaths":["native-document.ntp"]}`. Reply through `response.sock` with
+the exact identities/nonce and phase `completed`, or phase `failed` plus a
+bounded message. No outputs, asset IDs, permissions or execution receipts may
+be supplied in that acknowledgement. The host removes the endpoint and request
+after each exchange. The `execute` wire action is available to the experimental
+host export primitive below; it still provides no native runtime admission or
+ordinary installed-Block execution by itself.
+
+Requests are at most 32 KiB; replies 8 KiB; acknowledgement time is five seconds
+by default and at most ten; each session has at most 64 adapter requests. The
+socket permits the observed application UID; its parent and control files are
+host-owned and the application mount is read-only. The SDK marks a request
+consumed before invoking its handler, so uncertain acknowledgements do not
+repeat a save on a later event-loop tick. Host cancellation joins endpoint
+cleanup. There is no network, filesystem, credential or spending proxy.
+
+The shared native draft host requests a save, rechecks authority, freezes the
+application and captures independently bounded files, then accepts state only
+through its revision store. An acknowledgement is untrusted: it establishes
+neither valid content nor output authority. Format/behavior review and artifact
+materialization remain separate requirements.
+
+### Experimental native export boundary
+
+An application-owned `execute` handler receives a declared operation, bounded
+typed inputs, a saved-state revision/digest, an execution ID and output mappings
+`{port,path,mimeType}`. Each path is relative to `/work` and starts with the
+host-created `.stillmade-exports/<executionId>/` directory. Create needed
+directories inside private scratch and use these fresh paths when invoking the
+real application's export API. Do not return an existing asset ID or old export
+path. Verify the actual operation succeeded before acknowledging; a void render
+call alone is insufficient. The host separately captures the declared files.
+
+The optional host composition binds an additional export-contract digest to
+package, application, runtime and input approval. It persists a pending dispatch
+before execution, rechecks the exact revision/dispatch, flushes the final native
+documents, then captures documents and output files under one retained cgroup
+freeze. A trusted format/storage materializer validates and stores the bytes;
+only an atomic host commit can accept typed outputs and the new state together.
+Receipt and artifact identities are host-owned. The application acknowledgement
+cannot mint them. Draft-only compositions remain unable to export.
+
+Current host preparation supports scalar/JSON and verified PNG image inputs,
+and UTF-8, JSON and bounded PNG output candidates. Other media inputs and output
+formats still need their own trusted materializers. PNG uses the existing application output
+materializer, including full decode limits and stored-byte readback. This is
+not a new native runtime grant or proof of complete application functionality.
+The host constructor/journal/storage callbacks are private implementation APIs;
+an LLM adapter must not import or implement them.
+
+Connected image inputs require `asset.read`, an exact input digest and a trusted
+project/asset-version storage reader. The authoritative store resolves the actual
+project owner separately from the editor actor; a collaborator is not assumed to
+own the project's assets. The host reuses full PNG decode and stored byte
+validation, enforces a 4 MiB aggregate input limit and rechecks authority before
+starting the application. It independently binds captured input hashes to
+the approved references. The application receives read-only `/inputs/<port>.png`
+files and operation values `{kind,path,mimeType,width,height,bytes,sha256}`;
+asset IDs, version IDs and storage URLs are not passed into application code.
+Inputs are distinct from `/restore` documents and writable `/work` output files.
+The input reader is a private host callback, not an SDK network/filesystem grant.
+Filesystem/decode checks pass with a fixture transport; the new `/inputs` native
+mount and actual Natron connected input have not yet been live verified.
+
+The focused native checks include filesystem/materializer lifecycle tests,
+not native application acceptance. They exercise actual captured files, decoded
+PNG storage, typed text consumption and rejection of missing/invalid artifacts,
+stale revisions, revocation, cancellation, forged acknowledgements and storage
+mismatches. Their transport is a fixture. Normal installation, server dispatch
+and editor leases, crash reconciliation, artifact cleanup after uncertain
+acceptance and actual native connected export remain unverified or unimplemented.
+Pending dispatches must be reconciled by the trusted host; timeout never permits
+an automatic fresh retry.
+
+Actual Natron acceptance, using a manual application-owned Qt adapter, verifies
+that the first file does not exist until StillMade's save request; an unsaved GUI
+node edit leaves the old file unchanged; the host request writes the new node;
+and reopen/edit/save writes another node. No native Save keyboard shortcut was
+used. Source/evidence are in
+`artifacts/repository-acceptance/natron-native-adapter-save-2026-09-30`. Normal
+installation, automatic authoring, server leases and connected exports remain
+unverified. This supersedes the earlier dirty-UI-save gap for this experimental
+protocol; it does not establish full native application import.
+
+### Runtime data is a dependency
+
+Inspect installation instructions for non-code resources as well as libraries:
+color profiles/LUTs, fonts, templates, schemas and support files can determine
+whether an application actually works. Record exact repositories/commits,
+selected complete resource trees, notices and how the application locates them.
+Never disable the intended feature or invent replacement data to conceal a
+missing dependency. A selected data profile is not the full executable closure
+or permission to launch/install anything.
+
+The private host acquisition helper `github-data-dependency.mjs` verifies selected
+ordinary data files against a complete pinned Git inventory and applies one
+aggregate request, byte and deadline budget across batches. Executable modes,
+links, unresolved submodules and sensitive paths are rejected by this profile.
+Existing quarantine, bundle and Linux materialization checks remain in effect.
+Other dependency types require their proper verification/admission path; an
+adapter cannot treat arbitrary installers as data.
+
+Actual Natron testing exposed a missing separately documented OpenColorIO
+configuration. Adding its verified complete Natron data profile resolved the
+failed PNG reader/writer render, and decoded output pixels matched the input.
+The captured PNG also passed shared materialization/readback and an offline
+Revolver/SDK consumer check. This is a prerequisite verified with a manual
+adapter, not full compositing, normal native installation or automatic import.
+
+### Experimental headless CMake build family
+
+Native builds and interactive application sessions are separate runtime families.
+The private `linux-cmake-offline/1` preparation accepts an exact sealed Git source
+bundle, pinned CMakeLists.txt, bounded definitions/targets and candidate output
+paths. It independently rechecks every source entry against the complete bundle
+inventory before invoking a fixed toolchain. It does not accept installers,
+network grants, mounts, principals or caller-selected resource limits.
+
+The host profile uses an unprivileged isolated unit without a display socket,
+offline networking, read-only source, 512 MiB scratch, 1.5 GiB memory, zero swap,
+128 tasks, 150% CPU quota and a 1,200-second deadline. Observed kernel memory,
+swap, CPU and task limits must match policy. Interactive session limits remain
+unchanged. Candidate files are independently captured through descriptor-relative
+reads while the actual cgroup is frozen, with per-file and aggregate byte limits.
+The unit must be stopped and its cgroup empty before the durable build fence can
+be released. Uncertain teardown retains the fence instead of starting a retry.
+
+Build-authored result JSON is untrusted. Neither a successful build nor captured
+binaries grant runtime admission, installation or proof of application behavior.
+Toolchain/runtime closure, artifact platform/ABI checks and actual application
+acceptance remain separate. This private preparation is not yet wired to the
+production workflow journal, aggregate resource lease, managed setup or automatic
+LLM adaptation/repair path. Offline policy tests pass; the native CMake supervisor
+and artifact capture have not yet been live verified.
+
+
+September 30 current implementation supersedes the earlier experimental build
+status: the base managed builder compiled cJSON and passed its 19 upstream tests;
+a separate reviewed Qt5 profile installed and verified its actual bindings and
+immutable toolchain identity. Native import now selects that profile from exact
+Git-verified build source and retains/resumes its candidate across setup. Natron's
+first actual source acquisition exceeded an unchanged compressed archive cap;
+profile consistency is unfinished. The manual Natron adapter validates as a draft
+and passes explicit fake-application protocol tests, but real execution and
+admission remain unverified. See the current authoring report and retained receipts.
+
+### Source completeness must survive fallback
+
+A source archive is a preview unless an independently verified complete Git tree
+backs it. Export rules can omit `.gitmodules`, Gitlinks and required ordinary
+files. Never infer completeness from the absence of those entries in an archive
+or compare an archive to an inventory derived from that same archive.
+
+The reviewed Qt5 builder now has a bounded Git metadata fallback: a fixed Git
+executable fetches an exact commit through a host-owned public GitHub broker,
+without checking out or executing repository code. The host verifies raw commit
+and reachable tree object hashes, discovers pinned submodules, and independently
+checks acquired file bytes. A controlled connection probe must establish actual
+loopback-only network access before dispatch; systemd property declarations alone
+are insufficient. Hosts without this runtime retain an incomplete preview and
+an actionable runtime requirement.
+
+Source reservations include each Git dispatch's maximum HTTP body bytes and
+requests. These conservative reservations are not measurements of bytes actually
+transferred. Unknown/failed acquisitions retain their maximum. Complete source,
+successful compilation and application/runtime admission remain distinct checks.
+
+Adapters may propose bounded literal source edits tied to original file hashes.
+The host reconstructs the edited bytes and retains original, patch and derived
+identities. These edits are currently validated but are not yet wired into native
+build execution; such candidates receive an explicit overlay-runtime requirement.