@mnstry/atelier 0.2.0-alpha.1 → 0.2.0-alpha.11

package/docs/upgrade.md

@@ -1,10 +1,133 @@
 # Upgrade Guide
 
+For an owner asking their agent to prepare an update, start with
+[guided upgrades](guided-upgrades.md). It separates release selection and staged
+installation from the exact local transaction and the owner's adoption decision.
+
 Use this guide when upgrading a copied private-domain or shared-project starter
 workspace between Atelier package releases. The flow is local-only: it does not
 provision repositories, contact a Git host, mutate the MNSTRY runtime, or write
 through a browser view.
 
+## Upgrading to 0.2.0-alpha.11
+
+This release tightens the Obsidian projection's app checks after independent
+review of 0.2.0-alpha.10: Atelier never coordinates with an Obsidian whose version it
+has not checked, the advice for a refused publication is true for every cause
+and appears in `status` as well as `open`, Linux resolves an app started
+through a differently named launcher, and the process check has a timeout.
+No project or machine setting needs to change.
+
+## Upgrading to 0.2.0-alpha.10
+
+This release fixes the first activation of the Obsidian projection. In
+0.2.0-alpha.9 the check for a running Obsidian matched Atelier's own maintenance
+service, so with Obsidian quit no view was ever published, and an Obsidian
+with no vault open was reported as an unsupported version. To publish a view
+for the first time, quit Obsidian, let the service publish, then run
+`atelier obsidian open --scope ID --adapter=obsidian-cli`. No project or
+machine setting needs to change.
+
+## Upgrading to 0.2.0-alpha.9
+
+This release fixes a defect in 0.2.0-alpha.8: the Obsidian maintenance service
+could not start from the published package (`atelier obsidian service start`
+reported `start-failed` with `service-exited-13`). Upgrade from 0.2.0-alpha.8
+directly; nothing else changes and no project or machine setting needs to be
+touched. 0.2.0-alpha.8 is deprecated.
+
+## Upgrading to 0.2.0-alpha.8
+
+This release adds typed advisory decision contracts and an experimental,
+opt-in Obsidian projection. Nothing is published for a project that does not
+enable `ext["mnstry.atelier.obsidian"]`; see [obsidian.md](obsidian.md).
+
+The link resolver that produces `links_to` edges changed in five classes
+(links inside code and front matter, directory links, links that climb above
+the repository root, malformed percent-encoding, and workspace-only wikilink
+and cross-repository edges). Regenerate committed graph artifacts after
+upgrading and review the difference; the classes are listed in the changelog
+and in [obsidian-contract.md](obsidian-contract.md).
+
+## Upgrading to 0.2.0-alpha.7
+
+This release adds optional evidence-bound local review and the external-project
+starter. Existing v1 locks and readers remain compatible. To use bound review,
+explicitly qualify each pack for the new root version, regenerate the graph and
+projection, and create a fresh run. Historical runs retain their original
+snapshot and never acquire renewed approval from an upgrade. See
+[local review](local-review.md) for the complete workflow.
+
+## Upgrading to 0.2.0-alpha.6
+
+This release adds Atelier Sync Deliverable Zero: a headless, local repository
+supervisor with explicit enrollment, complete repository observations,
+fast-forward-only reconciliation, pause/resume control, hash-chained local
+operation traces, and two-phase user-confirmed commit and publication. It does
+not add a desktop shell, semantic conflict resolution, force operations,
+telemetry, or unattended semantic writes.
+
+Consumers that adopt the new runtime should enroll one repository explicitly,
+treat watchers as hints rather than truth, require a fresh complete observation
+before each confirmed mutation, and keep commit and publication as separate
+user decisions. Existing consumers that do not import the runtime subpaths are
+contract-compatible and need only update their pinned dependency.
+
+## Upgrading to 0.2.0-alpha.5
+
+This release hardens public/private boundary enforcement, local serving,
+collaboration-ledger integrity, disclosure review, and release provenance.
+Documents valid against `0.2.0-alpha.0` remain contract-compatible, but some
+previously tolerated unsafe or ambiguous states now fail closed.
+
+- Projects using `atelier dev` must provide a generated
+  `atelier.manifest.json`; only enrolled, safe, realpath-validated static files
+  are served, and the sidecar accepts loopback traffic only.
+- Empty or malformed content-rule policies, incomplete Git reads, corrupt or
+  oversized collaboration ledgers, and unsafe manifest entries are now
+  blocking errors with typed CLI diagnostics.
+- Run `atelier disclosure check` before sharing tracked or staged content. A
+  private denylist is required by default and must remain outside the public
+  repository.
+- Release candidates are packed once, SHA-256-bound, and the exact audited
+  tarball is the artifact sent through npm trusted publishing.
+
+Re-run the boundary, disclosure, graph, readiness, and lock checks below after
+updating. If `atelier dev` previously served files without a manifest, generate
+and review the manifest before restarting it.
+
+## Upgrading to 0.2.0-alpha.4
+
+This is a presentation release. There are no contract changes and no runtime
+behaviour changes: documents valid against `0.2.0-alpha.0` remain valid, and
+`npm run contract:compat` is clean against the same epoch baseline. The README,
+package metadata, and public documentation now describe the Atelier as a
+repository substrate for people, agents, teams, and tools. Upgrading is a
+dependency bump.
+
+## Upgrading to 0.2.0-alpha.3
+
+No contract changes and no runtime behaviour changes: documents valid against
+`0.2.0-alpha.0` remain valid, and `npm run contract:compat` is clean against
+the same epoch baseline. Upgrading is a dependency bump.
+
+One thing worth knowing, because it changes what you type. Outside an
+installed workspace, use `npx mnstry-atelier` rather than `npx atelier`: the
+unscoped npm name `atelier` belongs to an unrelated third-party package, so a
+bare `npx atelier` there runs someone else's code. Inside an installed
+workspace both names resolve from `node_modules/.bin`, so npm scripts and
+workspace shells need no change.
+
+## Upgrading to 0.2.0-alpha.2
+
+No contract changes and no runtime behaviour changes: documents valid against
+`0.2.0-alpha.0` remain valid, and `npm run contract:compat` is clean against
+the same epoch baseline. Upgrading is a dependency bump.
+
+Note on version numbering: `0.2.0` was published in error and unpublished the
+same day. If a lockfile anywhere pins `0.2.0`, repin it to `0.2.0-alpha.2` —
+that number is permanently retired on npm and will not resolve.
+
 ## Upgrading to 0.2.0-alpha.1
 
 No contract changes and no authored-content changes: documents valid against
@@ -12,7 +135,7 @@ No contract changes and no authored-content changes: documents valid against
 the same epoch baseline. Upgrading is a dependency bump.
 
 Two things worth knowing. The package is now on the npm registry, so the
-install command changes from a Git reference to `@mnstry/atelier@0.2.0-alpha.1`
+install command changes from a Git reference to `@mnstry/atelier@0.2.0-alpha.2`
 — keep the `@mnstry/` scope, since the unscoped name belongs to an unrelated
 package. And a local sidecar that previously exited on a malformed request now
 answers it, so anything that supervised `atelier dev` through restarts can stop
@@ -62,16 +185,16 @@ For registry installs, pin the exact version and record the resolved version
 in the lockfile:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.1
-npx atelier lock write --project ./atelier.project.json
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.11
+npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
 For Git installs, pin the release tag rather than a branch, so the lock file
 records exactly what was reviewed:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.1"
-npx atelier lock write --project ./atelier.project.json
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.11"
+npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
 Before accepting upstream changes, run the non-mutating upgrade planner:
@@ -122,3 +245,30 @@ older workspaces and should not be used in new docs or package scripts.
 When unsure, fail closed: keep source in the private-domain workspace and move
 only a reviewed summary into the shared-project workspace through ordinary Git
 review.
+
+## Exact installed source and review history
+
+`atelier lock provenance --exact-source-required` and
+`atelier lock check --exact-source-required` refuse unverified bindings.
+Supported npm lock metadata is a declaration matched to the exact installation
+slot, including nested instances; a SHA in that declaration is not proof of the
+installed bytes. Linked/unsupported stores remain unresolved when no trustworthy
+instance evidence is available. Tarball/registry integrity is reported when
+available, without inventing a Git origin. Dirty, ignored or untracked executable
+inputs prevent verified checkout qualification. Inventory excludes Git metadata
+and dependency trees; two observed byte inventories must agree and match the commit tree, including when Git index hints conceal changes. A verified clean
+checkout does not authenticate an upstream publisher.
+
+Review snapshots and decisions are separate from historical v1 locks. See
+[pack lifecycle](extension-pack-lifecycle.md) and
+[inspection portability](review-portability.md) before replacing packs or moving
+state. Updating a package or a digest never silently renews old approval.
+
+## Exact local candidate transactions
+
+For the bounded, manually confirmed single-repository workflow, see
+[Local exact-plan upgrades](exact-upgrades.md). The `upgrade plan --save`,
+`upgrade apply --plan ... --confirm ...`, `upgrade status`, and recovery dry-run
+commands are separate from the legacy flag-based migration workflow above.
+They preserve history and honor existing commit hooks; they do not install a
+new package or activate a runtime.

package/docs/vault-service.md

@@ -0,0 +1,292 @@
+# Portable private artifact vaults (experimental)
+
+This is an optional hosted service contract, not part of the local authoring
+server. The core does not start a service, provision infrastructure, select an
+identity provider, or make network requests on import. A host explicitly binds
+provider SDKs and owns their network access, credentials, costs and operations.
+Canonical sources and editorial review remain in the consuming repository.
+Uploading a derived artifact does not satisfy an editorial publication gate.
+
+## HTTP contract
+
+- `GET /<vault>/<artifact-path>` and `HEAD` authenticate a browser session and
+  require exact owner issuer + subject equality. Every asset uses this route.
+- `POST /_publish/<vault>` requires a separate vault-scoped machine credential.
+  Browser cookies and Origin headers are refused on this endpoint. The JSON
+  body has schema `atelier-vault-publication/v1`, `contractVersion: "1.0.0"`,
+  `expectedRevision` (initially
+  zero), and `files: [{path, base64}]`. No URL retrieval or directory discovery
+  occurs. The caller explicitly selects all uploaded files and is responsible
+  for source selection, disclosure checks and any editorial approval.
+- Successful publication returns 201 and a receipt containing vault, revision
+  and the SHA-256 publication digest. Conflicts return 409. Retry after uncertain
+  delivery uses `GET /_publish/<vault>` with the same machine credential. It
+  returns only schema `atelier-vault-status/v1`, vault, revision and publication
+  digest (null before the first publication), never the file manifest. Compare
+  both revision and digest with the intended publication before declaring it
+  delivered. A differing digest or later revision requires reconciliation; do
+  not silently overwrite it. There is no automatic retry or idempotency promise.
+- Unauthenticated reads return 401; a host may route these to its established
+  sign-in UI. Missing and non-owned vaults both return 404. Failures return 503
+  without leaking adapter errors. No CORS grants or sharing bypass exist.
+- Requests are limited to 4 MiB encoded JSON, 100 files, conservative ASCII
+  paths and allowlisted types. HTML and CSS are supported with restrictive CSP;
+  scripts, SVG and arbitrary interactive applications are excluded. HTML is
+  sandboxed without same-origin or script privileges. PDF is a download.
+
+All output, including errors, is private/no-store. Content bytes are checked
+against the committed manifest before delivery. No public object URLs or
+presigned download redirects are returned. Revocation blocks subsequent
+checks; it cannot recall a response already authorized or a downloaded file.
+
+The optional `contractVersion` and inert `ext` containers follow the kit schema
+epoch. Extension data never grants authority and is not copied into artifacts.
+
+## Host interfaces
+
+Import the `@mnstry/atelier/vault` entrypoint. `createVaultService` takes:
+
+- `identity.read(request)` returns a verified `{issuer, subject}` or null. It
+  must verify signatures, issuer/audience, expiry and current revocation using
+  the chosen provider. Never derive identity from a caller-provided header.
+- `identity.publish(request, vault)` verifies a machine credential. The supplied
+  `vaultIdentity` helper hashes a high-entropy bearer credential and calls the
+  host's authoritative `lookupCredential(hash)`. A record contains `vault`,
+  `owner`, `revoked: false` and finite millisecond `expiresAt`. Generate at least
+  32 random bytes; never place credentials in repository files or URLs.
+- `metadata.get(vault)` returns owner, revision and manifest. `commit` compares
+  owner AND expected revision atomically before replacing the current manifest.
+- `storage.put(key, bytes)` and `get(key)` use private storage. Keys are generated
+  from validated vault IDs and byte digests; request paths never become keys.
+
+Metadata lookup and credential lookup must use authoritative current state,
+not eventually consistent caches. Provision vault ownership out of band; the
+publication endpoint cannot claim a vault or change ownership. A host identity
+migration must explicitly map issuer and subject, not match email strings.
+
+## Provider bindings
+
+`createVercelVault` composes Blob/PostgreSQL bindings into a Web handler.
+`createCloudflareVault` returns a Worker with per-request first-primary D1
+sessions, using `env.VAULT_OBJECTS` and `env.VAULT_DB`. Both require explicit
+verified-session and current-credential lookup functions from the host.
+
+
+Vercel: pass the host-installed `@vercel/blob` SDK to `vercelPrivateStorage` and
+an established PostgreSQL client object exposing `query(sql, args)` to `postgresVaultMetadata`. Use the
+exported `VAULT_TABLE_SQL` to initialize a new disposable/purpose-built store.
+Bind an established browser identity SDK to `verifySession`; the kit does not
+ship a bespoke login system. Route all vault paths through the handler. Do not
+copy artifact output into public/static deployment directories.
+
+Cloudflare: pass a private R2 binding to `r2PrivateStorage` and D1 to
+`d1VaultMetadata`. If using D1 read replication, pass a session with
+`first-primary` semantics so ownership lookup cannot use a stale replica.
+The Web Request/Response handler can run directly in a Worker. Disable public
+R2 access and do not attach a public R2 domain. All Worker/provider aliases must
+run the same handler; no cache rule or static-assets shortcut may bypass it.
+
+Each adapter puts immutable-in-meaning content-addressed bytes first, then
+switches the manifest through an atomic SQL update. Concurrent publications
+cannot overwrite a newer revision. Failed uploads can leave unreferenced
+private objects; garbage collection and retention are host responsibilities.
+There is no automatic deletion. Republishing a selected earlier artifact set
+at the current expected revision implements rollback as a new revision.
+
+References:
+- https://vercel.com/docs/vercel-blob/private-storage
+- https://developers.cloudflare.com/r2/api/workers/workers-api-reference/
+- https://developers.cloudflare.com/d1/worker-api/d1-database/
+
+## Qualification and remaining integration
+
+`node --test test/vault.test.mjs` exercises both storage adapters with SDK-shaped
+local doubles and a real SQLite engine behind both SQL interfaces. PostgreSQL
+placeholder translation in the test is a local double, not a PostgreSQL engine. This proves
+shared local behavior, not Vercel, R2, D1 or PostgreSQL hosted operation.
+
+Before serving real material: qualify the chosen identity SDK and browser
+login/revocation, deployed provider bindings, owner/wrong-owner/anonymous reads,
+all aliases and assets, CSS/image rendering under sandbox CSP, publication
+failure recovery, limits and credentials. Run a source-bound independent
+review. These are open gates. The implementation is not deployment-ready.
+The SDKs, production credential store, provisioning UI, CLI integration and
+hosted conformance runner remain consumer-host work for the next integration
+step. No existing deployment or protection setting is modified by this code.
+
+## Privacy gate and vault interface
+
+This is an experimental contract, not a qualified hosted product. The service
+requires a trusted `deployment: {id, origins}` binding. Origins are canonical
+HTTPS origins, including every deployment alias and direct handler origin (up
+to 16). The provider inspector must discover any additional bypass surfaces and
+refuse `completeInventory` if this binding is stale. Configuration evidence is
+trusted host input, never publisher/browser input or a repository assertion.
+
+The context carries vault, owner, publication digest, metadata revision, manifest, deployment,
+request origin/path, phase, and `objects: [{key, sha256, size}]`. Object keys are
+explicit even before upload. The evaluator requires both vault home routes and
+every manifest path on every configured origin, plus every unique object key.
+Each route target has `kind: "route"`, URL and expected SHA-256; each storage
+target has `kind: "storage"`, URL, key, SHA-256 and size. Storage URLs are only
+passed to the trusted inspector/transport, never returned to the browser.
+
+Privacy checks ask whether **anonymous and other-user identities are denied**.
+They never request an owner's session or probe as the author. Owner rendering
+and login continuity are separate functional acceptance checks. Consequently,
+probes against the real handler exit at authorization without recursively
+entering the privacy gate. No substitute owner route or privileged inspection
+endpoint is used to manufacture a verified verdict.
+
+`privacy.verify(context)` collects before-upload and before-activation evidence.
+Before upload, authoritative provider configuration must attest private storage
+and owner-only routing before private bytes are written. Denial probes of paths
+that do not yet exist are supplementary; a 404 alone cannot prove future bytes
+will be protected. A host can supply public synthetic canary markers to check
+its protection machinery, without uploading private data to discover exposure.
+Before activation, the same gate checks actual staged object locations and all
+planned artifact routes. Unactivated artifact paths may return 404; their future
+owner rendering is not asserted by a denial verdict. Provider configuration and
+the handler's authorization remain the preventive controls. A change between
+checks refuses activation, but cannot atomically lock external provider policy.
+
+Read requests call only `privacy.current(context)`, which must load stored
+current evidence. They never collect probes. Missing, expired, wrong-owner,
+wrong-deployment, wrong-publication or incomplete evidence blocks delivery.
+`createVaultPrivacyState({probe, load, compareAndSet})` supplies an explicit refresher and
+host-owned evidence persistence. Call `refresh(context)` after commit and from
+the host scheduler with the current authoritative manifest and owner. Use the public
+`createVaultContext({vault, record, deployment})` export to build that context
+from `metadata.get(vault)`; it includes storage keys, revision and null handling
+without copying internal formats. Refresh rejects a missing, negative or
+non-integer revision before reading the evidence store. Activation
+evidence is deliberately not promoted to read evidence; owner delivery remains
+unavailable until the first successful read-phase refresh. Refresh failure never
+extends a validity window. A policy change requires immediate host invalidation;
+the kit cannot discover that change from an evidence-store read alone.
+
+The store key includes deployment ID and vault. `load(key)` returns an immutable
+snapshot `{version, evidence}`; a missing record is `{version: 0, evidence: null}`.
+`compareAndSet(key, evidence, {expectedVersion})` must atomically compare the
+version, increment it on success and return exactly `true`, or return `false`
+without writing. Its transaction must refuse replacement of any exposure alarm
+and refuse older metadata revisions for green evidence. Exposure alarms must
+be allowed to replace newer green evidence regardless of the alarm revision: a
+staged-only exposure can concern objects outside the current manifest. Separate atomic load/save calls are not
+sufficient. Protect the store from publishers; no unconditional save adapter is
+accepted. Evidence and refresh contexts bind the authoritative metadata revision.
+
+Green evidence retains the version loaded before collection. A conflict refuses
+that collection; it is never converted into an unconditional overwrite. Before
+returning non-read green evidence, the wrapper reloads the store to notice an
+alarm another instance persisted during probing. This check is not atomic with
+metadata activation; hosts must still own provider containment and transactions.
+
+Exposure alarms use a different path. The wrapper latches the original evidence
+in memory, then reloads and conditionally writes it, with at most three attempts
+per verify/refresh call. If a durable alarm already exists, no rewrite is needed.
+If writes conflict, each retry uses a fresh snapshot. If the store throws or the
+attempt bound is reached, verify/refresh rejects with the public
+`VaultAlarmPersistenceError` (`code: "VAULT_ALARM_NOT_PERSISTED"`, `evidence`).
+Hosts must alert on that error and retry the same wrapper after store recovery.
+Its next verify/refresh retries the original pending evidence without re-probing,
+so a vanished or staged-only exposure is not forgotten. Store calls themselves
+must have host-enforced deadlines; the attempt bound is not a network timeout.
+
+`current` performs no persistence retry or probe and immediately returns any
+local alarm, including an unpersisted one. The service's gate translates the
+typed error into an exposed/refused result with `persistence: "unconfirmed"`;
+the underlying wrapper API exposes the typed error to host refresh/verification
+callers. Other instances and restarts cannot see an unpersisted memory latch,
+so durable-store failure is an unresolved incident, never a success receipt.
+Best-effort notification alone does not settle it.
+
+No alarm-clear API is provided. Recovery is an explicit host operator procedure:
+contain the external exposure, verify restored controls, reconcile durable state,
+then replace affected handler instances. Restart alone is not recovery and does
+not clear a successfully persisted alarm. No provider containment is implemented
+by this module.
+
+### Reusable denial probe collector
+
+`createVaultPrivacyProbe({inspect, request, onExposure})` takes an explicit
+provider inspector and transport, without choosing a network implementation.
+The transport receives only anonymous/otherUser identity, manual redirects and
+an AbortSignal; otherUser must be a dedicated synthetic unauthorized principal,
+not another real person's session. Never give this collector an owner credential.
+The inspector supplies configuration, policy revision and the full target list.
+Configuration must report `ownerOnly`, `privateStorage`, `completeInventory`.
+
+The collector supports at most 2000 targets, sufficient for 100 files across
+16 origins plus home routes and unique storage objects. Exceeding the bound or
+the configurable whole-operation deadline (maximum/default 60 seconds) refuses
+verification; completeness is never replaced with sampling. The serial transport
+may not finish a large inventory in time. Qualify provider latency and choose a
+smaller deployment or a separately reviewed batched collector if needed. The
+current 60-second validity starts at collection start; refresher period plus
+worst-case collection time must be strictly less than 60 seconds. A minute
+schedule or a near-deadline collection cannot provide continuous availability.
+These defaults are an open product limitation, not a scheduling recommendation.
+
+Each target supplies an expected SHA-256, optionally a public synthetic `canary`
+marker of at least 32 characters. Nonempty whole-body digest or embedded canary matches
+are exposure even on error or already-followed responses. Zero-byte artifacts
+remain valid: an empty refusal discloses no bytes and never raises an exposure
+alarm. Home-route digests may use an inspector-defined placeholder; use an
+explicit public canary to detect actual listing disclosure. Nonempty 401/403/404 bodies without a match
+are inconclusive, because a body fragment is not proof of non-disclosure. Empty
+401/403/404 responses count as denial. Arbitrary HTML and 5xx are inconclusive.
+Login redirects may match trusted `loginEndpoints: [{url, queryKeys}]`; endpoints
+are exact HTTPS origin/path, with an explicit allowlist of supported non-secret
+parameter names. Credential-bearing or unexpected parameters, hosts and paths
+are inconclusive. The collector never follows redirects or copies login values
+into evidence. This verifies refusal, not the return-to user experience.
+
+Evidence starts its freshness window at collection start (60 seconds), binds
+owner/operation/publication/deployment, retains target digests and keys, and
+re-inspects provider policy using canonical object-key ordering. An unauthorized
+content observation returns immediately and stays `exposed` even if evidence
+later expires. Optional `onExposure(evidence)` is a best-effort host notification;
+it cannot delay or downgrade the alarm and is not durable containment. Hosts
+must persist incidents and enforce provider-side containment independently.
+No scheduler, provider configuration collector, credential store, containment
+operation, or hosted transport is bundled here.
+
+A provider bypass can expose staged objects after a successful preflight. This
+handler can refuse its own delivery/activation but cannot close an external
+public origin or delete orphaned bytes. Before real material, qualify atomic
+incident persistence, provider protection restoration, staging retention/deletion
+and owner-visible recovery. Do not advertise a denied handler response as global
+containment or an observed denial as permanent privacy.
+
+### Reference interface and browser qualification
+
+The reference home provides privacy status, revision, navigation, search, empty
+and unavailable states, accessible labels and responsive layout. Its status
+states that unauthorized-access checks passed at a recorded time, not that owner
+rendering or every future provider state is proven. Generated HTML stays outside
+the trusted shell under script-disabled sandbox CSP. This is a minimal reference
+interface, not full authoring/review parity.
+
+**Open browser design gate:** opaque-origin sandboxed HTML may lose SameSite
+session cookies on CSS/image requests. Widening cookies can permit cross-site
+embedding. The kit does not silently remove sandbox isolation or widen cookie
+scope. A consuming host must qualify an isolated artifact-origin/session design,
+including Chromium/Firefox/WebKit subresources and refused cross-site embeds,
+before claiming browser-product readiness. No browser acceptance is claimed.
+
+### Source layouts
+
+The Node-only `@mnstry/atelier/vault/source` entrypoint exports
+`prepareVaultSource({root, paths, expectedRevision})`. Pass an absolute local
+artifact root and explicit relative file paths. A root can be a folder inside
+the authoring repository or a separate artifact checkout; neither is scanned
+automatically. It returns the publication request, digest and manifest without
+uploading anything. Keep machine-specific roots in local host configuration.
+
+The reader refuses symlinks, hard-linked files, path escapes, directories,
+unsupported formats and oversized bundles. It checks file identity and metadata
+around the read and binds the resulting bytes to the manifest. Run against a
+quiescent source tree; portable filesystem checks are not a sandbox against a
+malicious process concurrently replacing ancestor directories. The publication
+bundle is an immutable byte snapshot, not a live directory handle.

package/fixtures/atelier-coauthor/invalid/authority.v1.json

@@ -0,0 +1,5 @@
+{
+  "id": "sample-session",
+  "fields": [],
+  "publication": true
+}

package/fixtures/atelier-coauthor/valid/config.v1.json

@@ -0,0 +1,12 @@
+{
+  "id": "sample-session",
+  "fields": [
+    {
+      "id": "sample-field",
+      "source": {
+        "ref": "packet.md",
+        "digest": "0000000000000000000000000000000000000000000000000000000000000000"
+      }
+    }
+  ]
+}

package/fixtures/atelier-guide/invalid/authority.v1.json

@@ -0,0 +1,11 @@
+{
+  "schema": "mnstry.atelier-remote-capability@v1",
+  "id": "sample-capability",
+  "serviceRef": "https://example.invalid/mcp",
+  "inputSchemaDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "outputSchemaDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "maxInputBytes": 1024,
+  "implementation": "remote",
+  "executionAuthority": false,
+  "command": "execute"
+}

package/fixtures/atelier-guide/valid/capability.v1.json

@@ -0,0 +1,10 @@
+{
+  "schema": "mnstry.atelier-remote-capability@v1",
+  "id": "sample-capability",
+  "serviceRef": "https://example.invalid/mcp",
+  "inputSchemaDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "outputSchemaDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "maxInputBytes": 1024,
+  "implementation": "remote",
+  "executionAuthority": false
+}

package/fixtures/atelier-guide/valid/consent.v1.json

@@ -0,0 +1,11 @@
+{
+  "schema": "mnstry.atelier-guide-consent@v1",
+  "offerDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "capabilityDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "payloadDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "engagementRevision": 1,
+  "status": "approved",
+  "validFrom": "2026-01-01T00:00:00Z",
+  "expiresAt": "2026-01-02T00:00:00Z",
+  "authority": "local-assertion-only"
+}

package/fixtures/atelier-guide/valid/engagement.v1.json

@@ -0,0 +1,7 @@
+{
+  "schema": "mnstry.atelier-guide-engagement@v1",
+  "offerDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "revision": 0,
+  "status": "proposed",
+  "authority": "local-assertion-only"
+}

package/fixtures/atelier-guide/valid/offer.v1.json

@@ -0,0 +1,10 @@
+{
+  "schema": "mnstry.atelier-guide-offer@v1",
+  "id": "sample-offer",
+  "guideId": "sample-guide",
+  "capabilityIds": [
+    "sample-capability"
+  ],
+  "deliverableReview": "required",
+  "commercialAuthority": false
+}

package/fixtures/atelier-intake/invalid/authority.v1.json

@@ -0,0 +1,9 @@
+{
+  "schema": "mnstry.atelier-intake-completion@v1",
+  "attemptId": "sample",
+  "attemptDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "outputDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "bytes": 12,
+  "integrity": "verified",
+  "semanticAcceptance": "accepted"
+}

package/fixtures/atelier-intake/valid/attempt.v1.json

@@ -0,0 +1,8 @@
+{
+  "schema": "mnstry.atelier-intake-attempt@v1",
+  "attemptId": "sample",
+  "blobId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "extractorId": "plain-text",
+  "extractorVersion": "1",
+  "configurationDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+}

package/fixtures/atelier-intake/valid/completion.v1.json

@@ -0,0 +1,9 @@
+{
+  "schema": "mnstry.atelier-intake-completion@v1",
+  "attemptId": "sample",
+  "attemptDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "outputDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "bytes": 12,
+  "integrity": "verified",
+  "semanticAcceptance": "pending"
+}

package/fixtures/atelier-intake/valid/source.v1.json

@@ -0,0 +1,7 @@
+{
+  "schema": "mnstry.atelier-intake-source@v1",
+  "sourceRef": "sample.txt",
+  "blobId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "bytes": 12,
+  "originalMutation": false
+}

package/fixtures/atelier-repository-observation/invalid/complete-with-blocker.v1.json

@@ -0,0 +1,18 @@
+{
+  "schema": "atelier-repository-observation@v1",
+  "observedAt": "2026-08-25T00:00:00.000Z",
+  "complete": true,
+  "root": "/workspace/project",
+  "filesystem": {
+    "supported": true,
+    "code": "local-filesystem"
+  },
+  "blockers": [
+    {
+      "code": "partial-clone-unsupported",
+      "message": "partial clones may omit required Git objects",
+      "details": {}
+    }
+  ],
+  "warnings": []
+}