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

package/src/upgrade/upgrade.mjs

@@ -3,7 +3,7 @@ import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
 import { buildGraph } from '../graph/graph.mjs'
-import { buildProjectProjection } from '../projection/project.mjs'
+import { buildProjectProjection, buildProjectManifest } from '../projection/project.mjs'
 import { buildReadiness } from '../readiness/readiness.mjs'
 import { validateJsonSchema } from '../export/atelier-export-contract.mjs'
 import {
@@ -14,6 +14,7 @@ import {
   resolvePathValue,
   writeJson,
 } from '../project/config.mjs'
+import { packageRootFrom } from '../project/package-root.mjs'
 import {
   BOUNDARY_POLICY_SCHEMA,
   checkBoundaryPolicy,
@@ -22,6 +23,10 @@ import {
 } from '../boundary/policy.mjs'
 import { bundledMnstryReadinessPackV1 } from '../readiness-protocols/bundled-pack.mjs'
 import { loadExtensionPacks } from '../extension-packs/loader.mjs'
+import { inspectPackageProvenance, legacyPackageSource } from './provenance.mjs'
+import { prepareUpgrade, applySavedUpgrade, upgradeOperationStatus, recoverUpgradeDryRun, explainSavedUpgrade } from './transaction.mjs'
+import { renderUpgradeExplanation } from './explanation.mjs'
+export { prepareUpgrade, applySavedUpgrade, upgradeOperationStatus, recoverUpgradeDryRun, explainSavedUpgrade }
 
 export const ATELIER_LOCK_SCHEMA = 'mnstry.atelier-lock@v1'
 export const ATELIER_MIGRATION_SCHEMA = 'mnstry.atelier-migration@v1'
@@ -36,7 +41,7 @@ export const MIGRATION_CLASSES = new Set([
   'breaking',
 ])
 
-const packageRoot = path.resolve(new URL('../..', import.meta.url).pathname)
+const packageRoot = packageRootFrom(import.meta.url)
 const packageJson = readJson(path.join(packageRoot, 'package.json'))
 const lockSchema = readJson(path.join(packageRoot, 'contracts', 'atelier-lock.v1.schema.json'))
 const REVIEW_MARKER_RE = /(Atelier-Boundary-Review|boundary-review)\s*:\s*(approved|reviewed)/i
@@ -76,18 +81,7 @@ function packageGitSha() {
 }
 
 function packageSource() {
-  const gitSha = packageGitSha()
-  const repository = packageGitRoot()
-    ? git(packageRoot, ['config', '--get', 'remote.origin.url']) || packageJson.repository?.url || null
-    : packageJson.repository?.url || null
-  if (repository && gitSha) return { type: 'git', repository, gitSha }
-  if (repository) return { type: 'private_github', repository, gitSha: null }
-  return {
-    type: 'local_path',
-    path: '.',
-    gitSha,
-    repository,
-  }
+  return legacyPackageSource(inspectPackageProvenance(packageRoot, { includeInventory: false }))
 }
 
 export function lockPathForProject(project) {
@@ -171,7 +165,7 @@ export function buildAtelierLock({ project, templateId = 'existing-workspace', a
   }
 }
 
-export function writeAtelierLock({ project, templateId = 'existing-workspace' } = {}) {
+export function writeAtelierLock({ project, templateId } = {}) {
   const lockPath = lockPathForProject(project)
   // Packs load in throwing mode on purpose: a broken extension pack cannot be
   // locked. Lock verification is disabled for this one load so re-pinning is
@@ -179,8 +173,18 @@ export function writeAtelierLock({ project, templateId = 'existing-workspace' }
   // moved or set aside, so it exists at every observable point, and writeJson
   // replaces it atomically (temp file + renameSync). A load failure throws
   // before any write and leaves the previous lock untouched.
+  const previous = readOptionalJson(lockPath)
+  if (previous) {
+    const errors = validateJsonSchema(lockSchema, previous)
+    if (errors.length) throw new Error(`cannot preserve invalid lock history: ${errors.join('; ')}`)
+  }
   const { packs } = loadExtensionPacks(project, { verifyLock: false })
-  const lock = buildAtelierLock({ project, templateId, packs })
+  const lock = buildAtelierLock({ project, templateId: templateId || previous?.template?.id || 'existing-workspace', packs })
+  if (previous) {
+    lock.appliedMigrations = previous.appliedMigrations
+    lock.lastSuccessfulUpgrade = previous.lastSuccessfulUpgrade
+    lock.template = { ...previous.template, ...(templateId ? { id: templateId } : {}) }
+  }
   writeJson(lockPath, lock)
   return lock
 }
@@ -518,13 +522,7 @@ function runGeneratedRefresh(project) {
   const projection = buildProjectProjection(project)
   fs.mkdirSync(path.dirname(projection.output), { recursive: true })
   fs.writeFileSync(projection.output, projection.html)
-  writeJson(path.join(project.outputRoot, 'atelier.manifest.json'), {
-    schema: 'mnstry.atelier-manifest@v1',
-    generatedAt: 'deterministic',
-    graphPath: project.graphPath,
-    entry: 'index.html',
-    nodes: projection.graph.nodes.map((node) => ({ id: node.id, title: node.title, audience: node.audience, path: node.path })),
-  })
+  writeJson(path.join(project.outputRoot, 'atelier.manifest.json'), buildProjectManifest(project, projection))
   writeJson(project.readinessPath, buildReadiness({ project, graph }))
 }
 
@@ -616,7 +614,7 @@ export function checkAtelierLock(project) {
   if (lock && lock.package?.version !== packageJson.version) errors.push(`lock package version ${lock.package?.version} does not match ${packageJson.version}`)
   if (lock && lock.contracts?.boundaryPolicy !== BOUNDARY_POLICY_SCHEMA) errors.push(`lock boundary policy contract must be ${BOUNDARY_POLICY_SCHEMA}`)
   const loadedPolicy = loadPolicyForLock(project)
-  if (lock?.boundaryPolicy?.digest && loadedPolicy.digest && lock.boundaryPolicy.digest !== loadedPolicy.digest) {
+  if (lock && (lock.boundaryPolicy?.digest ?? null) !== loadedPolicy.digest) {
     errors.push('boundary policy digest has changed; run upgrade --dry-run before applying')
   }
   if (lock) {
@@ -655,24 +653,62 @@ export function checkAtelierLock(project) {
 export function runLockCommand(argv = process.argv.slice(2)) {
   const args = parseArgs(argv)
   const subcommand = args._[0] || 'check'
+  if (subcommand === 'provenance') {
+    const report = inspectPackageProvenance(packageRoot)
+    console.log(JSON.stringify(report, null, 2))
+    process.exitCode = args['exact-source-required'] && !report.sourceVerified ? 1 : 0
+    return
+  }
   const project = commandProject({ argv })
   if (subcommand === 'write') {
-    const lock = writeAtelierLock({ project, templateId: firstString(args.template, args['template-id'], project.config?.template?.id) || 'existing-workspace' })
+    const lock = writeAtelierLock({ project, templateId: firstString(args.template, args['template-id'], project.config?.template?.id) || undefined })
     console.log(JSON.stringify({ ok: true, path: lockPathForProject(project), lock }, null, 2))
-    process.exit(0)
+    process.exitCode = 0
+    return
   }
   if (subcommand === 'check') {
     const report = checkAtelierLock(project)
+    if (args['exact-source-required']) {
+      report.provenance = inspectPackageProvenance(packageRoot)
+      if (!report.provenance.sourceVerified) { report.ok = false; report.errors.push('installed package source is unverified') }
+    }
     console.log(JSON.stringify(report, null, 2))
-    process.exit(report.ok ? 0 : 1)
+    process.exitCode = report.ok ? 0 : 1
+    return
   }
   console.error(`Unknown lock command: ${subcommand}`)
-  process.exit(1)
+  process.exitCode = 1
 }
 
 export function runUpgradeCommand(argv = process.argv.slice(2)) {
   const args = parseArgs(argv)
-  const project = commandProject({ argv })
+  const project = commandProject({ argv, writeLocalState: args._[0] !== 'explain' })
+  if (['plan', 'apply', 'status', 'recover', 'explain'].includes(args._[0])) {
+    try {
+      let result
+      if (args._[0] === 'explain') {
+        if (!firstString(args.plan)) throw new Error('--plan is required')
+        if (args.format != null && !['json', 'markdown'].includes(args.format)) throw new Error('--format must be json or markdown')
+        result = explainSavedUpgrade({ project, planFile: args.plan })
+        console.log(args.format === 'markdown' ? renderUpgradeExplanation(result) : JSON.stringify(result, null, 2))
+        return
+      } else if (args._[0] === 'plan') {
+        if (args.save !== true) throw new Error('exact planning requires --save')
+        result = prepareUpgrade({ project })
+      } else if (args._[0] === 'apply') {
+        if (!firstString(args.plan)) throw new Error('--plan is required')
+        result = applySavedUpgrade({ project, planFile: args.plan, confirm: args.confirm })
+      } else if (args._[0] === 'status') {
+        result = upgradeOperationStatus({ project, operationId: args.operation })
+      } else {
+        if (args['dry-run'] !== true) throw new Error('recovery supports --dry-run only; mutation requires a separately reviewed recovery plan')
+        result = recoverUpgradeDryRun({ project, operationId: args.operation })
+      }
+      console.log(JSON.stringify(result, null, 2))
+      process.exitCode = result.ok === false ? 1 : 0
+    } catch (error) { console.error(error.message); process.exitCode = 1 }
+    return
+  }
   const confirmBreaking = asArray(args['confirm-breaking']).concat(firstString(args['confirm-breaking']) ? [String(args['confirm-breaking'])] : [])
   const allowDirtyGenerated = Boolean(args['allow-dirty-generated'])
   if (args.check) {

package/src/vault/hosts.mjs

@@ -0,0 +1,21 @@
+import { createVaultService } from './service.mjs'
+import { vaultIdentity } from './identity.mjs'
+import { r2PrivateStorage, vercelPrivateStorage } from './storage.mjs'
+import { d1VaultMetadata, postgresVaultMetadata } from './metadata.mjs'
+
+/** Vercel host passes its established session verifier, credential store and SDKs. */
+export function createVercelVault({ blob, postgres, verifySession, lookupCredential, privacy, deployment }) {
+  return createVaultService({ privacy, deployment, storage: vercelPrivateStorage(blob), metadata: postgresVaultMetadata(postgres), identity: vaultIdentity({ verifySession, lookupCredential, privacy, deployment }) })
+}
+/** Create a handler per request so D1 sessions cannot carry stale bookmarks. */
+export function createCloudflareVault({ verifySession, lookupCredential, privacy, deployment }) {
+  vaultIdentity({ verifySession, lookupCredential })
+  async function handle(request, env) {
+    try {
+    const db = env.VAULT_DB.withSession('first-primary')
+    const identity = vaultIdentity({ verifySession: req => verifySession(req, env), lookupCredential: hash => lookupCredential(hash, env, db) })
+    return await createVaultService({ privacy, deployment, storage: r2PrivateStorage(env.VAULT_OBJECTS), metadata: d1VaultMetadata(db), identity })(request)
+    } catch { return new Response(null, { status: 503, headers: { "Cache-Control": "private, no-store", "X-Content-Type-Options": "nosniff" } }) }
+  }
+  return { fetch: handle }
+}

package/src/vault/identity.mjs

@@ -0,0 +1,19 @@
+/**
+ * The host verifies browser sessions using its established identity provider.
+ * Machine credentials are high-entropy secrets whose SHA-256 hashes are stored
+ * by the host. Lookup must read authoritative, current expiry/revocation state.
+ */
+import { digest } from './service.mjs'
+export function vaultIdentity({ verifySession, lookupCredential, now = () => Date.now() }) {
+  if (typeof verifySession !== 'function' || typeof lookupCredential !== 'function') throw new TypeError('Identity bindings required')
+  return {
+    read: request => verifySession(request),
+    async publish(request, vault) {
+      const value = request.headers.get('authorization')
+      if (!value || !/^Bearer [A-Za-z0-9_-]{43,128}$/.test(value)) return null
+      const record = await lookupCredential(await digest(new TextEncoder().encode(value.slice(7))))
+      if (!record || record.vault !== vault || record.revoked !== false || !Number.isFinite(record.expiresAt) || record.expiresAt <= now()) return null
+      return record.owner
+    },
+  }
+}

package/src/vault/index.mjs

@@ -0,0 +1,7 @@
+export { createVaultService, preparePublication } from './service.mjs'
+export { vaultIdentity } from './identity.mjs'
+export { r2PrivateStorage, vercelPrivateStorage } from './storage.mjs'
+export { VAULT_TABLE_SQL, d1VaultMetadata, postgresVaultMetadata } from './metadata.mjs'
+export { createVercelVault, createCloudflareVault } from './hosts.mjs'
+export { assessVaultPrivacy, createVaultPrivacyState, createVaultContext, VaultAlarmPersistenceError } from './privacy.mjs'
+export { createVaultPrivacyProbe } from './probe.mjs'

package/src/vault/interface.mjs

@@ -0,0 +1,11 @@
+const escape = value => String(value).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]))
+export function renderVaultHome({ vault, revision, manifest, privacy, query = '' }) {
+  const files = manifest.filter(file => /\.(html|pdf|txt)$/.test(file.path))
+  const matches = files.filter(file => file.path.toLowerCase().includes(query.toLowerCase()))
+  const verified = privacy.status === 'verified'
+  const label = verified ? 'Unauthorized-access checks passed' : privacy.status === 'exposed' ? 'Privacy failure — external routes may remain exposed' : 'Privacy not verified — access blocked'
+  const list = verified ? matches.map(file => `<li><a href="/${escape(vault)}/${file.path.split('/').map(encodeURIComponent).join('/')}">${escape(file.path)}</a><span>${escape(file.type.split(';')[0])}</span></li>`).join('') : ''
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escape(vault)} · Atelier</title><style>
+  *{box-sizing:border-box}body{margin:0;background:#f6f5ef;color:#20382d;font:17px/1.6 system-ui,sans-serif}main{max-width:960px;margin:auto;padding:clamp(20px,5vw,64px)}header{border-bottom:1px solid #cad3c7;padding-bottom:24px}h1{font-size:clamp(30px,6vw,52px);line-height:1.15;overflow-wrap:anywhere}a{color:inherit;text-underline-offset:4px}a:focus-visible,input:focus-visible,button:focus-visible{outline:3px solid #28734e;outline-offset:4px}.status{padding:16px;border:1px solid #738975;border-radius:8px;margin:24px 0}.blocked{background:#fff0dc;border-color:#936125}label{display:block;font-weight:600}form{display:flex;gap:12px;flex-wrap:wrap}input{flex:1;min-width:0;font:inherit;padding:12px;border:1px solid #738975;border-radius:6px}button{font:inherit;padding:12px 20px;background:#20382d;color:white;border:0;border-radius:6px}ul{list-style:none;padding:0}li{padding:20px 0;border-bottom:1px solid #cad3c7}li a{display:block;overflow-wrap:anywhere}li span,footer{font-size:14px;color:#506354}footer{margin-top:40px}.skip{position:absolute;left:-10000px}.skip:focus{left:16px;top:8px}</style></head><body><a class="skip" href="#artifacts">Skip to artifacts</a><main><header><p>ATELIER · PRIVATE VAULT</p><h1>${escape(vault)}</h1><p>Published revision ${escape(revision)} · ${files.length} artifact${files.length === 1 ? '' : 's'}</p></header><section class="status ${verified ? '' : 'blocked'}" aria-label="Privacy status"><strong>${label}</strong><p>${escape(privacy.reason)}</p>${verified ? `<small>Checked ${escape(new Date(privacy.checkedAt).toISOString())}. Authorization and evidence freshness are checked when you open an artifact.</small>` : '<p>Ask the workspace operator to verify destination protection, then reload. Artifacts are unavailable until the checks pass.</p>'}</section><label for="search">Find an artifact</label><form role="search" method="get" action="/${escape(vault)}/"><input id="search" name="q" type="search" value="${escape(query)}" maxlength="200"><button type="submit">Search</button></form>${verified ? `<ul id="artifacts" tabindex="-1" aria-label="Artifacts">${list}</ul>${matches.length ? '' : `<p>${files.length ? 'No artifacts match your search.' : 'No artifacts have been published yet.'}</p>`}` : ''}<footer>This website displays published artifacts. Saving or reviewing source material does not publish it. Generated artifacts run without script privileges.</footer></main></body></html>`
+}
+export const vaultHomePolicy = "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'"

package/src/vault/metadata.mjs

@@ -0,0 +1,31 @@
+/** SQL adapters require pre-provisioned vaults; neither endpoint creates owners. */
+export const VAULT_TABLE_SQL = `CREATE TABLE atelier_vaults (
+  id TEXT PRIMARY KEY,
+  owner_issuer TEXT NOT NULL,
+  owner_subject TEXT NOT NULL,
+  revision INTEGER NOT NULL DEFAULT 0,
+  manifest TEXT NOT NULL DEFAULT '[]',
+  publication TEXT
+)`
+function record(row) {
+  return row ? { owner: { issuer: row.owner_issuer, subject: row.owner_subject }, revision: Number(row.revision), manifest: JSON.parse(row.manifest), publication: row.publication } : null
+}
+export function d1VaultMetadata(db) {
+  return {
+    async get(vault) { return record(await db.prepare('SELECT * FROM atelier_vaults WHERE id = ?').bind(vault).first()) },
+    async commit(vault, update) {
+      const result = await db.prepare('UPDATE atelier_vaults SET revision = revision + 1, manifest = ?, publication = ? WHERE id = ? AND revision = ? AND owner_issuer = ? AND owner_subject = ?')
+        .bind(JSON.stringify(update.manifest), update.publication, vault, update.expectedRevision, update.owner.issuer, update.owner.subject).run()
+      return result.success === true && result.meta.changes === 1
+    },
+  }
+}
+export function postgresVaultMetadata(db) {
+  return {
+    async get(vault) { return record((await db.query('SELECT * FROM atelier_vaults WHERE id = $1', [vault])).rows[0]) },
+    async commit(vault, update) {
+      const result = await db.query('UPDATE atelier_vaults SET revision = revision + 1, manifest = $1, publication = $2 WHERE id = $3 AND revision = $4 AND owner_issuer = $5 AND owner_subject = $6', [JSON.stringify(update.manifest), update.publication, vault, update.expectedRevision, update.owner.issuer, update.owner.subject])
+      return result.rowCount === 1
+    },
+  }
+}

package/src/vault/privacy.mjs

@@ -0,0 +1,148 @@
+/** Trusted host evidence only: never accept evidence from a publisher. */
+const unknown = reason => ({ status: 'unknown', reason })
+export function vaultObjects(vault, manifest) {
+  return [...new Map(manifest.map(file => [`${vault}/${file.sha256}`, { key: `${vault}/${file.sha256}`, sha256: file.sha256, size: file.size }])).values()]
+}
+export function validDeployment(deployment) {
+  if (!deployment || typeof deployment.id !== 'string' || !deployment.id || !Array.isArray(deployment.origins) || !deployment.origins.length || deployment.origins.length > 16) return false
+  return new Set(deployment.origins).size === deployment.origins.length && deployment.origins.every(origin => {
+    try { const u = new URL(origin); return u.protocol === 'https:' && u.origin === origin && !u.username && !u.password } catch { return false }
+  })
+}
+export function assessVaultPrivacy(evidence, context) {
+  const { vault, publication, revision, phase, owner, deployment, manifest = [], objects = [], request, now = Date.now() } = context
+  // Exposure is a sticky alarm, not authorization. Even stale/mismatched trusted
+  // evidence must not turn a known exposure into an ordinary availability error.
+  if (evidence?.targets?.some?.(t => t?.anonymous === 'content' || t?.otherUser === 'content')) return { status: 'exposed', reason: 'Unauthorized content observed. This handler refuses delivery; external routes may remain exposed.' }
+  if (!evidence || evidence.vault !== vault || evidence.publication !== publication) return unknown('Protection evidence does not match this publication.')
+  if (!Number.isSafeInteger(revision) || revision < 0 || evidence.revision !== revision) return unknown('Protection evidence does not match the metadata revision.')
+  if (evidence.phase !== phase || !['before-upload', 'before-activation', 'read'].includes(phase) || !owner?.issuer || !owner?.subject || evidence.owner?.issuer !== owner.issuer || evidence.owner?.subject !== owner.subject) return unknown('Protection evidence does not match the owner and operation.')
+  if (!validDeployment(deployment) || evidence.deployment?.id !== deployment.id || JSON.stringify(evidence.deployment?.origins) !== JSON.stringify(deployment.origins)) return unknown('Protection evidence does not match this deployment.')
+  if (request && (!deployment.origins.includes(request.origin) || (phase === 'read' && request.path !== `/${vault}` && request.path !== `/${vault}/` && !manifest.some(f => request.path === `/${vault}/${f.path}`)))) return unknown('Request is outside the verified inventory.')
+  if (!Number.isFinite(evidence.checkedAt) || !Number.isFinite(evidence.validUntil) || evidence.checkedAt > now || evidence.validUntil <= now || evidence.validUntil <= evidence.checkedAt || evidence.validUntil - evidence.checkedAt > 300000) return unknown('Protection evidence is missing or expired.')
+  if (typeof evidence.policyRevision !== 'string' || !evidence.policyRevision) return unknown('Provider policy identity is missing.')
+  const config = evidence.configuration
+  if (config?.ownerOnly !== true || config?.privateStorage !== true || config?.completeInventory !== true) return unknown('Provider protection or route inventory is unverified.')
+  if (!Array.isArray(evidence.targets) || !evidence.targets.length || evidence.targets.length > 2000) return unknown('Access checks are missing or oversized.')
+  const urls = new Set(), routes = new Set(), keys = new Set()
+  for (const target of evidence.targets) {
+    let url
+    try { url = new URL(target.url) } catch { return unknown('Access check URL is invalid.') }
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || urls.has(url.href)) return unknown('Access check inventory is invalid.')
+    urls.add(url.href)
+    if (target.anonymous !== 'denied' || target.otherUser !== 'denied') return unknown('Required access checks did not complete successfully.')
+    if (target.kind === 'storage') {
+      if (!objects.some(o => o.key === target.key && o.sha256 === target.sha256 && o.size === target.size)) return unknown('Storage check does not match a staged object.')
+      keys.add(target.key)
+    } else if (target.kind === 'route') {
+      if (!deployment.origins.includes(url.origin)) return unknown('Access check uses an unconfigured origin.')
+      const file = manifest.find(f => url.pathname === `/${vault}/${f.path}`)
+      const home = url.pathname === `/${vault}` || url.pathname === `/${vault}/`
+      if (!home && (!file || file.sha256 !== target.sha256)) return unknown('Access check does not match a manifest path and digest.')
+      routes.add(url.href)
+    } else return unknown('Access check target is invalid.')
+  }
+  for (const origin of deployment.origins) {
+    for (const path of [`/${vault}`, `/${vault}/`, ...manifest.map(f => `/${vault}/${f.path}`)]) if (!routes.has(origin + path)) return unknown('A configured route is missing from access checks.')
+  }
+  for (const object of objects) if (!keys.has(object.key)) return unknown('A staged storage object is missing from access checks.')
+  return { status: 'verified', reason: 'Configured routes refused unauthorized access at the recorded check time. Owner rendering is qualified separately.', checkedAt: evidence.checkedAt, validUntil: evidence.validUntil, policyRevision: evidence.policyRevision }
+}
+export async function verifyVaultPrivacy(privacy, context) {
+  const method = context.phase === 'read' ? 'current' : 'verify'
+  if (typeof privacy?.[method] !== 'function') return unknown('No provider privacy evidence is configured.')
+  try { return assessVaultPrivacy(await privacy[method](context), context) }
+  catch (error) {
+    if (error instanceof VaultAlarmPersistenceError) return { ...assessVaultPrivacy(error.evidence, context), persistence: 'unconfirmed' }
+    return unknown('Provider privacy verification is unavailable.')
+  }
+}
+
+/** The host must alert/retry this failure; the local read latch remains set. */
+export class VaultAlarmPersistenceError extends Error {
+  constructor(evidence, cause) {
+    super('Vault exposure is latched locally but durable persistence is unconfirmed.', { cause })
+    this.name = 'VaultAlarmPersistenceError'
+    this.code = 'VAULT_ALARM_NOT_PERSISTED'
+    this.evidence = evidence
+  }
+}
+
+/** Public builder keeps refresh contexts aligned with service storage keys. */
+export function createVaultContext({ vault, record, deployment, request, phase = 'read' }) {
+  if (!record || !Number.isSafeInteger(record.revision) || record.revision < 0 || !Array.isArray(record.manifest)) throw new TypeError('Authoritative revision and manifest required')
+  return { vault, owner: record.owner, publication: record.publication ?? null, revision: record.revision, manifest: record.manifest, objects: vaultObjects(vault, record.manifest), deployment, ...(request ? { request } : {}), phase }
+}
+
+/** Host-owned versioned evidence store. Refresh is explicit; reads never probe. */
+export function createVaultPrivacyState({ probe, load, compareAndSet }) {
+  if (typeof probe?.verify !== 'function' || typeof load !== 'function' || typeof compareAndSet !== 'function') throw new TypeError('Probe and versioned evidence store required')
+  const alarms = new Map()
+  const key = context => {
+    if (!Number.isSafeInteger(context?.revision) || context.revision < 0) throw new TypeError('Authoritative nonnegative metadata revision required')
+    return JSON.stringify([context.deployment?.id, context.vault])
+  }
+  const exposed = (evidence, context) => assessVaultPrivacy(evidence, context).status === 'exposed'
+  async function snapshot(id, context) {
+    const record = await load(id)
+    if (!record || !Number.isSafeInteger(record.version) || record.version < 0 || !Object.hasOwn(record, 'evidence')) throw new TypeError('Invalid evidence store snapshot')
+    if (exposed(record.evidence, context)) alarms.set(id, { evidence: record.evidence, persisted: true })
+    return record
+  }
+  async function persistAlarm(id, context) {
+    // Alarm writes may replace newer green evidence regardless of revision.
+    // Reload on conflict, never reuse a stale version or retry green evidence.
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (alarms.get(id).persisted) return alarms.get(id).evidence
+      try {
+        const record = await snapshot(id, context)
+        if (alarms.get(id).persisted) return alarms.get(id).evidence
+        const evidence = alarms.get(id).evidence
+        if (await compareAndSet(id, evidence, { expectedVersion: record.version }) === true) {
+          alarms.set(id, { evidence, persisted: true })
+          return evidence
+        }
+      } catch (cause) { throw new VaultAlarmPersistenceError(alarms.get(id).evidence, cause) }
+    }
+    throw new VaultAlarmPersistenceError(alarms.get(id).evidence, new Error('Alarm write conflict limit reached'))
+  }
+  async function collect(context) {
+    const id = key(context)
+    // Pending latches retry persistence without re-probing a possibly vanished
+    // or staged-only exposure. Confirmed durable alarms need no rewrite.
+    if (alarms.has(id)) return persistAlarm(id, context)
+    const previous = await snapshot(id, context)
+    if (alarms.has(id)) return persistAlarm(id, context)
+    if (previous.evidence?.revision > context.revision) return null
+    const evidence = await probe.verify(context)
+    if (exposed(evidence, context)) {
+      if (!alarms.has(id)) alarms.set(id, { evidence, persisted: false })
+      return persistAlarm(id, context)
+    }
+    if (alarms.has(id)) return persistAlarm(id, context)
+    if (context.phase !== 'read') {
+      // Another instance may have latched an incident during the slow probe.
+      // This is still a check, not a transaction with metadata activation.
+      const latest = await snapshot(id, context)
+      if (alarms.has(id)) return persistAlarm(id, context)
+      return latest.evidence?.revision > context.revision ? null : evidence
+    }
+    // Green writes retain their original version. Conflicts and store failures
+    // must never be interpreted as a successful refresh.
+    if (await compareAndSet(id, evidence, { expectedVersion: previous.version }) !== true) {
+      await snapshot(id, context)
+      return alarms.has(id) ? persistAlarm(id, context) : null
+    }
+    return alarms.has(id) ? persistAlarm(id, context) : evidence
+  }
+  return {
+    verify: collect,
+    async current(context) {
+      const id = key(context)
+      if (alarms.has(id)) return alarms.get(id).evidence
+      const record = await snapshot(id, context)
+      return alarms.get(id)?.evidence ?? record.evidence
+    },
+    async refresh(context) { return collect({ ...context, phase: 'read' }) },
+  }
+}

package/src/vault/probe.mjs

@@ -0,0 +1,89 @@
+import { digest } from './service.mjs'
+const canonical = value => JSON.stringify(value, (_, item) => item && typeof item === 'object' && !Array.isArray(item) ? Object.fromEntries(Object.keys(item).sort().map(k => [k, item[k]])) : item)
+const MAX_BYTES = 4 * 1024 * 1024
+const cleanUrl = value => {
+  const url = new URL(value)
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) throw new Error('Unsafe probe URL')
+  return url.href
+}
+async function classify(response, target, loginUrls) {
+  if (!(response instanceof Response)) return 'unknown'
+  const reader = response.body?.getReader()
+  const chunks = []; let length = 0
+  try {
+    for (; reader;) {
+      const { value, done } = await reader.read()
+      if (done) break
+      length += value.byteLength
+      if (length > MAX_BYTES) { await reader.cancel(); return 'unknown' }
+      chunks.push(value)
+    }
+  } finally { reader?.releaseLock() }
+  const bytes = new Uint8Array(length); let offset = 0
+  for (const value of chunks) { bytes.set(value, offset); offset += value.length }
+  // Content exposure wins over misleading error or redirect status codes.
+  if (length > 0 && (await digest(bytes) === target.sha256 || (typeof target.canary === 'string' && target.canary.length >= 32 && new TextDecoder().decode(bytes).includes(target.canary)))) return 'content'
+  if (response.redirected) return 'unknown'
+  if ([401, 403, 404].includes(response.status)) return length === 0 ? 'denied' : 'unknown'
+  if ([302, 303, 307, 308].includes(response.status)) {
+    try {
+      const location = new URL(response.headers.get('location'), target.url)
+      if (location.protocol !== 'https:' || location.username || location.password || location.hash) return 'unknown'
+      const endpoint = loginUrls.find(item => item.url === location.origin + location.pathname)
+      return endpoint && [...location.searchParams.keys()].every(key => endpoint.queryKeys.includes(key)) ? 'denied' : 'unknown'
+    } catch { return 'unknown' }
+  }
+  return 'unknown'
+}
+/**
+ * inspect(context) is a trusted provider configuration/inventory collector.
+ * request({url,identity,redirect,signal}) is host transport; credentials never
+ * cross identities or redirects. No global fetch or ambient credentials here.
+ * Each collection re-inspects policy after probing to refuse changed settings.
+ */
+export function createVaultPrivacyProbe({ inspect, request, now = () => Date.now(), timeoutMs = 60000, onExposure }) {
+  if (typeof inspect !== 'function' || typeof request !== 'function' || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60000) throw new TypeError('Explicit probe bindings required')
+  return {
+    async verify(context) {
+      const controller = new AbortController()
+      let timer
+      const checkedAt = now()
+      const deadline = new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('Probe deadline exceeded')) }, timeoutMs) })
+      const collect = async () => {
+        const inventory = structuredClone(await inspect(context, { signal: controller.signal }))
+        if (!inventory || !Array.isArray(inventory.targets) || !inventory.targets.length || inventory.targets.length > 2000) throw new Error('Invalid probe inventory')
+        const targets = inventory.targets.map(target => {
+          if (!target || !/^[a-f0-9]{64}$/.test(target.sha256)) throw new Error('Expected content digest required')
+          return { ...target, url: cleanUrl(target.url) }
+        })
+        const loginUrls = (inventory.loginEndpoints ?? []).map(item => {
+          if (!Array.isArray(item.queryKeys) || item.queryKeys.some(key => !['state', 'redirect_uri', 'redirect_url', 'returnTo', 'next', 'client_id', 'response_type', 'scope', 'nonce', 'code_challenge', 'code_challenge_method'].includes(key))) throw new Error('Unsafe login parameters')
+          return { url: cleanUrl(item.url), queryKeys: item.queryKeys }
+        })
+        const evidence = results => ({ vault: context.vault, publication: context.publication, revision: context.revision, phase: context.phase, owner: context.owner, deployment: context.deployment, checkedAt, validUntil: checkedAt + 60000, policyRevision: inventory.policyRevision, configuration: inventory.configuration, targets: results })
+        const results = []
+        for (const target of targets) {
+          const result = { url: target.url, kind: target.kind, sha256: target.sha256, key: target.key, size: target.size }
+          for (const identity of ['anonymous', 'otherUser']) {
+            if (controller.signal.aborted) throw new Error('Probe aborted')
+            try { result[identity] = await classify(await request({ url: target.url, identity, redirect: 'manual', signal: controller.signal }), target, loginUrls) }
+            catch { result[identity] = 'unknown' }
+            if (result[identity] === 'content') {
+              const alarm = evidence([...results, result])
+              // Notification cannot delay or downgrade the exposure verdict. The
+              // host owns durable incident persistence and provider containment.
+              if (typeof onExposure === 'function') Promise.resolve().then(() => onExposure(alarm)).catch(() => {})
+              return alarm
+            }
+          }
+          results.push(result)
+        }
+        const after = await inspect(context, { signal: controller.signal })
+        if (canonical(after) !== canonical(inventory)) throw new Error('Provider protection changed during verification')
+        return evidence(results)
+      }
+      try { return await Promise.race([collect(), deadline]) }
+      finally { clearTimeout(timer); controller.abort() }
+    },
+  }
+}