@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.15

package/src/commands/obsidian.mjs

@@ -17,7 +17,7 @@ import { BUILT_IN_OPERATIONS, UNAVAILABLE_APPLY_OPERATION, createObsidianRegistr
 import { LIFECYCLE_PRIMITIVES, readServiceStatusDocument, requestServiceTick, runtimeRelease, serviceStatus, startService, stopService } from '../runtime/obsidian/lifecycle.mjs'
 import {
   DECISIONS, ONLY_YOU_AUDIENCES, authorizeAutomaticApply, defaultMachineSettings, ensureWorkspaceIdentity, installApplyPolicy, localPointerPath, protectedRoots,
-  readInstalledApplyPolicy, readMachineSettings, revokeApplyPolicy, withDecision, writeMachineSettings,
+  readInstalledApplyPolicy, readLocalPointer, readMachineSettings, revokeApplyPolicy, withDecision, writeMachineSettings,
 } from '../runtime/obsidian/machine-settings.mjs'
 import {
   currentLoginItemPlan, installLoginItem, loginItemDataRoot, loginItemLabel, loginItemStarter, loginItemStatus, planLoginItem, projectNameOf, readLoginItemRecord, realNodePath,
@@ -29,7 +29,7 @@ import { pluginPresenceOf, turnPluginOnNext, withPluginFilesPending, withPluginR
 import { planViewAdd, viewFromRequest, writeViewPlan } from '../runtime/obsidian/project-views.mjs'
 import { askGoAhead, createQuestioner } from '../runtime/obsidian/questions.mjs'
 import { readServiceSettings } from '../runtime/obsidian/service-record.mjs'
-import { resolveServiceWorkspace } from '../runtime/obsidian/service.mjs'
+import { resolveServiceWorkspace, serviceLocationCheck } from '../runtime/obsidian/service.mjs'
 import { STARTUP_PLATFORMS, buildStartupAdapter, startupSearchPath } from '../runtime/obsidian/startup-adapters.mjs'
 import { OBSIDIAN_SETTINGS_FILE, obsidianSandboxedBuild, obsidianUserDataDir, readObsidianSettings } from '../projection/obsidian/publication/vault-list.mjs'
 import { checkVaultParent, projectDisplayName, vaultFolderName } from '../runtime/obsidian/vault-location.mjs'
@@ -69,7 +69,7 @@ const PRODUCTION_ADAPTER = 'obsidian-cli'
 const MAX_POLICY_BYTES = 64 * 1024
 const AUDIENCE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
 
-export const USAGE = `Usage: atelier obsidian <operation> [--project atelier.project.json] [--data-root DIR] [--json] [--no-input]
+export const USAGE = `Usage: atelier obsidian <operation> [--project atelier.project.json | --personal-home DIR] [--data-root DIR] [--json] [--no-input]
 
   status                               Enablement, machine settings, service and per-view freshness. Read-only.
   settings                             What this machine remembers for this workspace, and how to change it. Read-only.
@@ -111,6 +111,11 @@ export const USAGE = `Usage: atelier obsidian <operation> [--project atelier.pro
                                        service publishes the view at once (with --adapter, one of an earlier release
                                        is replaced first).
 
+--personal-home DIR, given instead of --project, follows the generation last confirmed in that private home of a personal
+workspace (the personal-workspace module's selection); its views come from the overlay. Nothing here confirms one: while
+none is confirmed and current nothing is published, and status, open and service start refuse with the reason. service
+status and stop, unit --remove and uninstall find the service from the home alone. Who may see its vaults stays this
+machine's audience setting: owner only when undecided; an explicit clear stays empty.
 Reaching the installed app needs --adapter=${PRODUCTION_ADAPTER} once for a workspace; it is remembered after that.
 Obsidian's own settings file (obsidian.json) is written only while no Obsidian runs: open adds the view's vault to its
 list, turns its command line on (cli: true), and creates the file for an Obsidian that never started; every write is
@@ -139,7 +144,7 @@ Exit codes: 0 done; 1 internal error; 2 refusal or usage; 3 ran, and the answer
 // spelling of `project`); a test holds it to that.
 export const FLAGS = Object.freeze({
   json: 'flag', 'allow-stale': 'flag', 'restart-obsidian': 'flag', print: 'flag', install: 'flag', remove: 'flag', help: 'flag', 'no-input': 'flag', 'allow-synced-location': 'flag', all: 'flag', default: 'flag', 'allow-empty': 'flag', yes: 'flag',
-  project: 'value', 'project-config': 'value', 'data-root': 'value', scope: 'value', 'consent-actor': 'value', actor: 'value', adapter: 'value', 'wait-ms': 'value', repo: 'value', tag: 'value',
+  project: 'value', 'project-config': 'value', 'personal-home': 'value', 'data-root': 'value', scope: 'value', 'consent-actor': 'value', actor: 'value', adapter: 'value', 'wait-ms': 'value', repo: 'value', tag: 'value',
   expand: 'value', folder: 'values',
 })
 
@@ -276,6 +281,7 @@ const NEXT = Object.freeze({
   'login-item-remove-failed': 'see `atelier obsidian status`; `atelier obsidian service unit --remove` tries again',
   'login-item-file-unsafe': 'the login item\'s file is a link or not a regular file and is left alone; remove it by hand, then try again',
   'invalid-login-item': 'the login item record in private state does not validate; inspect it, remove it, then install the login item again',
+  'selection-history-shortened': 'records of the selection history were removed after this process read them; put them back, or run the command in a process of its own, which reads the history as it now stands',
 })
 
 // The login item of `status`, in words.
@@ -372,10 +378,16 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
 
     const dataRoot = flags['data-root'] === undefined ? options.dataRoot : path.resolve(cwd, flags['data-root'])
     const configFlag = flags.project ?? flags['project-config']
-    const loadProject = options.loadProject ?? (() => resolveProjectConfig({ argv: configFlag === undefined ? [] : [`--project=${path.resolve(cwd, configFlag)}`], cwd, env, writeLocalState: false }))
+    // A personal home is followed instead of a project: the generation confirmed there is loaded (composed in this
+    // thread, as for a command run once), and the service's workspace is located from the home alone.
+    const personalHome = flags['personal-home'] === undefined ? null : path.resolve(cwd, flags['personal-home'])
+    if (personalHome !== null && configFlag !== undefined) refuse('usage', '--personal-home is given instead of --project, not with it')
+    const selection = personalHome === null ? null : await import('../runtime/obsidian/personal-selection.mjs')
+    const loadProject = options.loadProject ?? (selection !== null ? () => selection.loadSelectedProject({ personalHome, dataRoot, env, platform }) : () => resolveProjectConfig({ argv: configFlag === undefined ? [] : [`--project=${path.resolve(cwd, configFlag)}`], cwd, env, writeLocalState: false }))
+    const locateProject = selection === null ? null : () => selection.locatePersonalHome({ personalHome })
     const registry = createObsidianRegistry({ reservedOperations: BUILT_IN_OPERATIONS, contributions: contributions ?? await loadContributions(contributionsDirectory === undefined ? {} : { directory: contributionsDirectory }) })
     const applyAvailable = registry.extensions.applyOperation() !== UNAVAILABLE_APPLY_OPERATION
-    const lifecycle = { loadProject, dataRoot, env, platform, ...(options.probeTimeoutMs === undefined ? {} : { probeTimeoutMs: options.probeTimeoutMs }) }
+    const lifecycle = { loadProject, ...(locateProject === null ? {} : { locateProject }), dataRoot, env, platform, ...(options.probeTimeoutMs === undefined ? {} : { probeTimeoutMs: options.probeTimeoutMs }) }
 
     // The adapter of this run: given now, or remembered by this workspace (read only when the real entry has no flag).
     const chooseAdapter = () => selectAdapter({ flag: flags.adapter, remembered: flags.adapter === undefined && production === true ? rememberedAdapter() : null, production, env })
@@ -458,8 +470,8 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
     const pluginOf = async (scopeId) => pluginPresenceOf((await readServiceStatusDocument(lifecycle, lifecycleRules)).document, scopeId)
     const pluginLine = (plugin) => `${plugin.present ? `; plugin present (Obsidian ${plugin.appVersion})` : plugin.reason === 'turned-off-in-this-vault' ? '; plugin turned off in this vault' : `; plugin not present (${plugin.reason})`}${plugin.files === 'waits-for-app' ? '; plugin files wait for the app' : ''}`
 
-    // A project bound to a personal workspace takes its views from the overlay, and has no place for these decisions
-    // yet: the operations that would write them refuse before anything is resolved or written.
+    // A personal binding takes its views from the overlay and keeps its audience owner only (or explicitly empty).
+    // Operations outside those machine decisions refuse before anything is resolved or written.
     const refuseOnPersonalBinding = async (project, operation) => (await import('../projection/obsidian/personal-workspace.mjs')).refuseOnPersonalBinding(project, operation)
     const configured = () => {
       const project = loadProject()
@@ -470,7 +482,7 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
     // Private state of this workspace, created on demand for an operation that writes it.
     const writable = () => {
       const { project, enablement } = configured()
-      ensureWorkspaceIdentity({ project, ...(dataRoot === undefined ? {} : { dataRoot }) })
+      ensureWorkspaceIdentity({ project, ...(dataRoot === undefined ? {} : { dataRoot }), validate: serviceLocationCheck({ project, dataRoot, env, platform }) })
       const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform, create: true })
       return { project, enablement, workspace, repositoryRoots: protectedRoots(project), now: isoTime(clock) }
     }
@@ -617,10 +629,10 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
     const removeUnit = async () => {
       if (!STARTUP_PLATFORMS.includes(platform)) buildStartupAdapter({ platform })
       const manager = await managerSeam()
-      const removed = await removeLoginItem({ loadProject, dataRoot, env, platform, manager, clock })
+      const removed = await removeLoginItem({ loadProject: locateProject ?? loadProject, dataRoot, env, platform, manager, clock })
       const failed = removed.removed !== true && removed.reason !== undefined && removed.reason !== 'workspace-not-prepared'
       if (failed) return { exit: EXIT.notSuccess, document: { loginItem: removed }, human: [`login item not removed: ${removed.reason}${removed.message ? ` (${removed.message})` : ''}`, `Next: ${NEXT[removed.reason] ?? 'see `atelier obsidian status`'}`] }
-      const remembered = removed.reason === 'workspace-not-prepared' ? false : rememberLoginItem('off')
+      const remembered = removed.reason === 'workspace-not-prepared' ? false : rememberLoginItem('off', { locate: true })
       let service = null
       if (removed.removed === true) {
         let entry = null
@@ -645,9 +657,18 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
     // The person's answer to "start at login?", remembered for this workspace as the `loginItem` decision of its machine
     // settings, given on the command line. By whom: the actor named, else a person at a terminal by the account's name,
     // else nobody known. Answers whether it wrote; an answer already remembered is not written again.
-    const rememberLoginItem = (choice) => {
-      if (readable().enablement.reason === 'not-configured') return false
-      const { workspace, repositoryRoots, now } = writable()
+    const rememberLoginItem = (choice, { locate = false } = {}) => {
+      let workspace, repositoryRoots, now
+      if (locate && locateProject !== null) {
+        const project = locateProject()
+        workspace = resolveServiceWorkspace({ project, dataRoot, env, platform })
+        if (!workspace?.workspaceRoot) return false
+        repositoryRoots = protectedRoots(project)
+        now = isoTime(clock)
+      } else {
+        if (readable().enablement.reason === 'not-configured') return false
+        ;({ workspace, repositoryRoots, now } = writable())
+      }
       const current = machineOf(workspace) ?? defaultMachineSettings({ workspaceId: workspace.workspaceId, updatedAt: now })
       if (current.decisions.loginItem?.choice === choice) return false
       const decidedBy = flags['consent-actor'] ?? (interactive ? accountActor(account()) : null)
@@ -681,7 +702,7 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
       }
       const vaults = [...new Set([...underDataRoot, ...allocated])].sort()
       const userDataDir = obsidianUserDataDir({ platform, env })
-      return { vaults, privateState: workspace?.workspaceRoot ?? null, projectFile: project.configPath ?? null, pointer: project.configPath ? localPointerPath(project) : null, obsidianList: userDataDir === null ? null : path.join(userDataDir, OBSIDIAN_SETTINGS_FILE) }
+      return { vaults, privateState: workspace?.workspaceRoot ?? null, projectFile: project.configPath ?? null, pointer: typeof project.configDir === 'string' && readLocalPointer(project) !== null ? localPointerPath(project) : null, obsidianList: userDataDir === null ? null : path.join(userDataDir, OBSIDIAN_SETTINGS_FILE) }
     }
 
     // Where a view's vault is, or will be: { path, origin }. A view the next tick will place is shown where it would go,
@@ -720,7 +741,10 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
             const plugin = withPluginFilesPending(pluginView(running, workspace, scopeId), report.freshness)
             return enablement.state === 'disabled' ? { ...report, outcome: 'disabled', reason: enablement.reason, next: OPENING_OUTCOMES.disabled.next, plugin } : { ...report, plugin }
           })
+        // The confirmed selection a personal home's project was loaded under; reported, never confirmed here.
+        const pinned = selection === null ? null : selection.personalSelectionOf(project)
         const document = {
+          ...(pinned === null ? {} : { selection: { generationId: pinned.generationId, sequence: pinned.sequence } }),
           enablement: { state: enablement.state, reason: enablement.reason, defaultScopeId: enablement.defaultScopeId }, workspace: { workspaceId, prepared: workspace !== null },
           machine: shownMachine(machineOf(workspace), workspace), apply: applyShown,
           service: { state: service.state, reason: service.reason ?? null, address: service.address ?? null, runtimeId: service.record?.runtimeId ?? null, pid: service.record?.pid ?? null, lastTick: running?.lastTick ?? null, lastError: running?.lastError ?? null, app },
@@ -729,6 +753,7 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
         return {
           exit: EXIT.ok, document,
           human: [
+            ...(pinned === null ? [] : [`personal workspace: generation ${pinned.generationId}, confirmed as selection ${pinned.sequence}`]),
             `obsidian: ${enablement.state} (${enablement.reason}); mode ${document.machine.maintenanceMode}; audiences ${document.machine.audienceAllow.join(', ') || 'none'}`,
             `remembered: ${decisionSummary(document.machine.decisions)}`,
             `service: ${service.state} (${service.reason ?? 'no reason'})${app ? `; app ${app.outcome} (${app.reason})` : ''}`,
@@ -885,7 +910,7 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
         // `me` stands for "only you". Named beside other audiences, it adds its own to theirs, and the list is the person's own choice.
         const audienceAllow = [...new Set(named.flatMap((item) => (item === 'me' ? ONLY_YOU_AUDIENCES : [item])))]
         const choice = named.length === 1 && named[0] === 'me' ? 'only-you' : 'custom'
-        await refuseOnPersonalBinding(loadProject(), `audience ${sub}`)
+        await refuseOnPersonalBinding(loadProject(), choice === 'only-you' ? 'audience set me' : `audience ${sub}`)
         const { workspace, repositoryRoots, now } = writable()
         const current = machineOf(workspace) ?? defaultMachineSettings({ workspaceId: workspace.workspaceId, updatedAt: now })
         // A vault that is only yours shows the notes that carry no classification too; any other list withholds them.
@@ -1073,17 +1098,19 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
       // Maintenance of this workspace ends here: the login item goes first, so its manager does not start the service
       // again, then the proven service stops. Everything a person made or may want back stays, and is named.
       async uninstall() {
-        const project = loadProject()
-        let workspace = null
-        try { const found = resolveServiceWorkspace({ project, dataRoot, env, platform }); workspace = found?.workspaceRoot ? found : null } catch (error) { if (!isTyped(error)) throw error }
+        const project = (locateProject ?? loadProject)()
+        // Only an established absence (no pointer, or no private state yet) is unprepared. A location or identity refusal
+        // stops here, before any login-item or service action, so uninstall never reports success over it.
+        const found = resolveServiceWorkspace({ project, dataRoot, env, platform })
+        const workspace = found?.workspaceRoot ? found : null
         const record = workspace === null ? null : readLoginItemRecord(workspace)
         // What is kept is read before anything is stopped or removed, so nothing it finds can stop the answer after that.
         const kept = keptLocations(project, workspace)
-        const item = record === null ? { removed: false, reason: 'not-installed' } : await removeLoginItem({ loadProject, dataRoot, env, platform, manager: await managerSeam(), clock })
+        const item = record === null ? { removed: false, reason: 'not-installed' } : await removeLoginItem({ loadProject: locateProject ?? loadProject, dataRoot, env, platform, manager: await managerSeam(), clock })
         const service = workspace === null ? { state: 'stopped', stopped: false, refused: false, reason: 'workspace-not-prepared' } : await stopService(lifecycle, lifecycleRules)
         const itemGone = item.removed === true || item.reason === 'not-installed' || item.reason === 'workspace-not-prepared'
         const serviceGone = service.stopped === true || service.state === 'stopped'
-        const remembered = workspace !== null && itemGone ? rememberLoginItem('off') : false
+        const remembered = workspace !== null && itemGone ? rememberLoginItem('off', { locate: true }) : false
         return {
           exit: itemGone && serviceGone ? EXIT.ok : EXIT.notSuccess,
           document: { loginItem: item, service, kept, rememberedNow: { loginItem: remembered ? 'off' : null } },
@@ -1095,6 +1122,7 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
             ...kept.vaults.map((vault) => `  vault           ${vault}`),
             ...(kept.privateState === null ? [] : [`  private state   ${kept.privateState}`]),
             `  project file    ${kept.projectFile ?? '(none)'}; its Obsidian settings stay`,
+            ...(kept.pointer === null ? [] : [`  workspace pointer ${kept.pointer}`]),
             ...(kept.obsidianList === null ? [] : [`  Obsidian's list ${kept.obsidianList}; the vaults stay in it`]),
           ],
         }

package/src/commands/review.mjs

@@ -7,6 +7,7 @@ import {
   createProtocolRegistry,
 } from '../extension-packs/loader.mjs'
 import { runProtocol } from '../readiness-protocols/runtime.mjs'
+import { bundledReadinessEnabled, requireSelectedReadinessProtocol } from '../readiness-protocols/bundled-selection.mjs'
 import { recordReviewEvidence } from '../readiness-protocols/evidence.mjs'
 import { createReviewStore } from '../collaboration/review-store.mjs'
 import {
@@ -73,7 +74,9 @@ let result
 if (args._[0] === 'run') {
   const registry = createProtocolRegistry({
     packs: loadExtensionPacks(project).packs,
+    includeBundled: bundledReadinessEnabled(project),
   })
+  requireSelectedReadinessProtocol(project, registry, args._[1])
   const answers = args.answers ? readJson(path.resolve(args.answers)) : {}
   const { run } = runProtocol(project, args._[1], {
     answers,

package/src/edge-policy/contract.mjs

@@ -0,0 +1,69 @@
+import crypto from 'node:crypto'
+import { canonicalize } from '../attestation/jcs.mjs'
+
+// Experimental adapter shapes, not an ontology or identity authority.
+export const EDGE_RECORD_SCHEMA = 'atelier-edge-record@experimental-v1'
+export const EDGE_DECISION_SCHEMA = 'atelier-edge-decision@experimental-v1'
+export const EDGE_FAMILIES = Object.freeze(['hyperlink', 'source-declaration', 'reviewed-assertion'])
+export const EDGE_ACTIONS = Object.freeze(['propose', 'approve', 'accept', 'reject', 'suspend', 'withdraw', 'supersede'])
+const digestPattern = /^sha256:[a-f0-9]{64}$/
+const text = (v, max = 256) => typeof v === 'string' && v.length > 0 && v.trim() === v && v.length <= max && !/[\u0000-\u001f\u007f]/.test(v)
+const object = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+const closed = (v, keys) => object(v) && Object.keys(v).length === keys.length && keys.every((k) => Object.hasOwn(v, k))
+const relativePath = (v) => text(v, 2048) && !v.includes('\\') && !v.startsWith('/') && !/^[A-Za-z]:/.test(v) && v.split('/').every((p) => p && p !== '.' && p !== '..')
+export const validNodeRef = (v) => closed(v, ['repoId', 'localId']) && text(v.repoId) && text(v.localId)
+export const bytesDigest = (v) => `sha256:${crypto.createHash('sha256').update(v).digest('hex')}`
+export const edgeDigest = (v) => bytesDigest(canonicalize(v))
+export function immutable(value) {
+  if (value && typeof value === 'object') {
+    for (const child of Object.values(value)) immutable(child)
+    Object.freeze(value)
+  }
+  return value
+}
+
+export function validSourceRef(v) {
+  return closed(v, ['repoId', 'path', 'revision', 'fileDigest', 'locator', 'citedDigest']) &&
+    text(v.repoId) && relativePath(v.path) && text(v.revision) && digestPattern.test(v.fileDigest) && digestPattern.test(v.citedDigest) &&
+    closed(v.locator, ['byteStart', 'byteEnd']) && Number.isSafeInteger(v.locator.byteStart) && v.locator.byteStart >= 0 &&
+    Number.isSafeInteger(v.locator.byteEnd) && v.locator.byteEnd > v.locator.byteStart
+}
+
+export function validateEdgeRecord(v) {
+  try {
+    if (!closed(v, ['schema', 'family', 'subject', 'predicate', 'object', 'home', 'origin', 'supports', 'policyDigest', 'proposalRef', 'sourceChange', 'qualifications'])) return false
+    if (v.schema !== EDGE_RECORD_SCHEMA || !EDGE_FAMILIES.includes(v.family) || !validNodeRef(v.subject) || !validNodeRef(v.object) || !text(v.predicate)) return false
+    if (!closed(v.home, ['repoId', 'path', 'readership']) || !text(v.home.repoId) || !relativePath(v.home.path) || !text(v.home.readership)) return false
+    if (!validSourceRef(v.origin) || !Array.isArray(v.supports) || v.supports.length > 256 ||
+      v.supports.some((s) => !closed(s, ['id', 'source']) || !text(s.id) || !validSourceRef(s.source)) || new Set(v.supports.map((s) => s.id)).size !== v.supports.length) return false
+    if (!digestPattern.test(v.policyDigest) || (v.proposalRef !== null && !text(v.proposalRef, 2048)) ||
+      !Array.isArray(v.qualifications) || v.qualifications.length > 64 || v.qualifications.some((q) => !text(q, 2048))) return false
+    if (v.family === 'hyperlink' && (v.predicate !== 'links-to' || v.sourceChange !== null)) return false
+    if (v.sourceChange !== null && (!closed(v.sourceChange, ['repoId', 'path', 'baseRevision', 'diffDigest', 'reviewRef']) ||
+      !text(v.sourceChange.repoId) || !relativePath(v.sourceChange.path) || !text(v.sourceChange.baseRevision) || !digestPattern.test(v.sourceChange.diffDigest) || !text(v.sourceChange.reviewRef, 2048))) return false
+    edgeDigest(v)
+    return true
+  } catch { return false }
+}
+
+export function validateEdgeDecision(v) {
+  try {
+    if (!closed(v, ['schema', 'recordDigest', 'sequence', 'previousDigest', 'action', 'actorId', 'at', 'policyDigest', 'reason', 'roles', 'signature'])) return false
+    if (v.schema !== EDGE_DECISION_SCHEMA || !digestPattern.test(v.recordDigest) || !Number.isSafeInteger(v.sequence) || v.sequence < 1 ||
+      (v.previousDigest !== null && !digestPattern.test(v.previousDigest)) || !EDGE_ACTIONS.includes(v.action) || !text(v.actorId) ||
+      !text(v.at) || !Number.isFinite(Date.parse(v.at)) || new Date(v.at).toISOString() !== v.at || !digestPattern.test(v.policyDigest) || !text(v.reason, 2048)) return false
+    if (!Array.isArray(v.roles) || v.roles.length > 3 || v.roles.some((r) => !closed(r, ['repoId', 'role']) || !text(r.repoId) || !['home-owner', 'endpoint-steward'].includes(r.role)) ||
+      new Set(v.roles.map((r) => canonicalize(r))).size !== v.roles.length) return false
+    if (v.action !== 'approve' && v.roles.length !== 0) return false
+    if (v.action === 'approve' && v.roles.length === 0) return false
+    if (!closed(v.signature, ['algorithm', 'keyId', 'value']) || !['ed25519', 'es256'].includes(v.signature.algorithm) || !text(v.signature.keyId) || !text(v.signature.value, 512)) return false
+    edgeDigest(v)
+    return true
+  } catch { return false }
+}
+
+export function edgeIdentity(record) {
+  if (!validateEdgeRecord(record)) throw new TypeError('invalid edge record')
+  const recordDigest = edgeDigest(record)
+  return Object.freeze({ edgeId: `edge:${recordDigest.slice(7)}`, recordDigest })
+}

package/src/edge-policy/policy.mjs

@@ -0,0 +1,142 @@
+import { verifyDocument } from '../attestation/sign.mjs'
+import { bytesDigest, edgeDigest, edgeIdentity, immutable, validateEdgeDecision, validateEdgeRecord } from './contract.mjs'
+
+const roleKey = (role) => `${role.role}\0${role.repoId}`
+const same = (a, b) => edgeDigest(a) === edgeDigest(b)
+const fail = (state, reason) => ({ state, eligible: false, reason })
+const decisions = new WeakSet()
+const seal = (value) => { const result = immutable(value); decisions.add(result); return result }
+function demand(value, reason) { if (!value) throw new Error(reason) }
+
+function validPolicy(p) {
+  return p && Object.keys(p).sort().join(',') === 'allowProposerReview,allowSharedSteward,version' &&
+    typeof p.version === 'string' && p.version.length > 0 && typeof p.allowProposerReview === 'boolean' && typeof p.allowSharedSteward === 'boolean'
+}
+
+// Content-bound occurrence identity only; this does not establish access,
+// source currency or eligibility. Keep caller-owned records untouched.
+export function edgeEvidenceOccurrences(record) {
+  const { edgeId } = edgeIdentity(record)
+  const occurrence = (id, source) => ({ id: `evidence:${edgeDigest({ edgeId, occurrenceId: id, source }).slice(7)}`, occurrenceId: id, source: structuredClone(source) })
+  return immutable([occurrence('origin', record.origin), ...record.supports.map((s) => occurrence(`support:${s.id}`, s.source))])
+}
+
+// Host functions are trusted integration ports. No record-supplied identity,
+// eligible flag, audience or local asserted review substitutes for these ports.
+// The host must hold one coherent current snapshot across an evaluation.
+export async function evaluateEdge(input, host) {
+  let record, events
+  try {
+    record = structuredClone(input.record)
+    events = structuredClone(input.events)
+    if (!validateEdgeRecord(record) || !Array.isArray(events) || events.length > 1024 || events.some((e) => !validateEdgeDecision(e))) return immutable(fail('suspended', 'invalid-input'))
+    immutable(record); immutable(events)
+    const identity = edgeIdentity(record)
+    const policy = immutable(structuredClone(host.policy))
+    demand(validPolicy(policy), 'policy-unavailable')
+    const policyDigest = edgeDigest(policy)
+    demand(typeof host.bindingId === 'string' && host.bindingId.length > 0, 'snapshot-binding-unavailable')
+    const base = { ...identity, family: record.family, policyDigest, verification: { checkedAt: host.now, bindingId: host.bindingId }, reviewRefs: [], triple: { subject: record.subject, predicate: record.predicate, object: record.object },
+      supportRefs: edgeEvidenceOccurrences(record), qualifications: record.qualifications,
+      sourceChange: record.sourceChange, history: events }
+    const result = (value) => seal({ ...base, ...value })
+    if (record.policyDigest !== policyDigest) return result(fail('suspended', 'policy-changed'))
+    const now = Date.parse(host.now)
+    demand(Number.isFinite(now), 'clock-unavailable')
+    const head = await host.readRecordHead(identity)
+    if (!head || head.recordDigest !== identity.recordDigest || head.eventCount !== events.length || head.eventDigest !== (events.length ? edgeDigest(events.at(-1)) : null)) return result(fail('suspended', 'history-head-mismatch'))
+    const origin = await host.verifyOrigin({ record, ...identity, policyDigest })
+    if (!origin || origin.recordDigest !== identity.recordDigest || origin.bindingId !== host.bindingId || origin.matches !== true) return result(fail('suspended', 'origin-mismatch'))
+    // Safe placement considers the home's entire intended readership, not only
+    // this reader. The host checks endpoints, all evidence and record metadata.
+    const placement = await host.checkSourceHome({ record, ...identity, policyDigest })
+    if (!placement || placement.recordDigest !== identity.recordDigest || placement.policyDigest !== policyDigest || placement.bindingId !== host.bindingId || placement.allowed !== true) return result(fail('suspended', 'unsafe-source-home'))
+    const endpoints = await Promise.all([record.subject, record.object].map((ref) => host.resolveEndpoint(ref)))
+    if (endpoints.some((e, i) => !e || !same(e.ref, [record.subject, record.object][i]) || e.current !== true || typeof e.stewardId !== 'string' || !e.stewardId)) return result(fail('suspended', 'endpoint-unavailable'))
+    const home = await host.resolveHomeOwner(record.home.repoId)
+    if (!home || typeof home.actorId !== 'string' || !home.actorId) return result(fail('suspended', 'home-owner-unavailable'))
+    for (const { source } of base.supportRefs) {
+      const observed = await host.readSource(source)
+      if (!observed || observed.revision !== source.revision || !(observed.bytes instanceof Uint8Array)) return result(fail('stale', 'source-changed'))
+      const bytes = Buffer.from(observed.bytes)
+      if (bytesDigest(bytes) !== source.fileDigest || source.locator.byteEnd > bytes.length ||
+        bytesDigest(bytes.subarray(source.locator.byteStart, source.locator.byteEnd)) !== source.citedDigest) return result(fail('stale', 'citation-changed'))
+    }
+    const semantic = record.family !== 'hyperlink'
+    const crossRepo = record.subject.repoId !== record.object.repoId
+    const governed = semantic && (crossRepo || record.family === 'reviewed-assertion' || events.length > 0)
+    if (!semantic) return result(events.length ? fail('suspended', 'navigation-has-decisions') : { state: 'active', eligible: true, assurance: 'navigation' })
+    if (!governed) return result({ state: 'active', eligible: true, assurance: 'source-declaration' })
+    if (!record.proposalRef || !record.sourceChange || record.sourceChange.repoId !== record.home.repoId || record.sourceChange.path !== record.home.path) return result(fail('suspended', 'source-owner-handoff-missing'))
+    // Review roles in this adapter are repository-scoped. Conflicting resource
+    // stewards inside one repository cannot be collapsed into one approval.
+    if (!crossRepo && endpoints[0].stewardId !== endpoints[1].stewardId) return result(fail('suspended', 'endpoint-steward-conflict'))
+    const required = [{ repoId: record.home.repoId, role: 'home-owner', actorId: home.actorId },
+      ...[...new Map(endpoints.map((e) => [e.ref.repoId, { repoId: e.ref.repoId, role: 'endpoint-steward', actorId: e.stewardId }])).values()]]
+    if (crossRepo && endpoints[0].stewardId === endpoints[1].stewardId && !policy.allowSharedSteward) return result(fail('suspended', 'shared-steward-not-delegated'))
+    let previous = null, state = 'draft', proposer = null, lastTime = -Infinity
+    const approvals = new Map()
+    for (const [index, event] of events.entries()) {
+      if (event.sequence !== index + 1 || event.previousDigest !== previous || event.recordDigest !== identity.recordDigest || event.policyDigest !== policyDigest || Date.parse(event.at) < lastTime || Date.parse(event.at) > now) return result(fail('suspended', 'decision-chain-invalid'))
+      if (['withdrawn', 'rejected', 'superseded', 'suspended'].includes(state)) return result(fail('suspended', 'terminal-history-continued'))
+      const binding = await host.resolveActorKey({ actorId: event.actorId, keyId: event.signature.keyId, at: host.now })
+      if (!binding || binding.actorId !== event.actorId || binding.revoked !== false || !Number.isFinite(Date.parse(binding.notBefore)) || !Number.isFinite(Date.parse(binding.expiresAt)) ||
+        Date.parse(binding.notBefore) > Date.parse(event.at) || Date.parse(binding.expiresAt) <= now || !verifyDocument(event, { publicKey: binding.publicKey }).valid) return result(fail('suspended', 'actor-key-unavailable'))
+      const grant = await host.authorizeDecision({ event, record, required, policyDigest })
+      if (!grant || grant.eventDigest !== edgeDigest(event) || grant.policyDigest !== policyDigest || grant.bindingId !== host.bindingId || grant.allowed !== true || grant.revoked !== false ||
+        !Number.isFinite(Date.parse(grant.notBefore)) || Date.parse(grant.notBefore) > Date.parse(event.at) || !Number.isFinite(Date.parse(grant.expiresAt)) || Date.parse(grant.expiresAt) <= now) return result(fail('suspended', 'decision-grant-unavailable'))
+      if (event.action === 'propose') {
+        if (state !== 'draft') return result(fail('suspended', 'invalid-transition'))
+        proposer = event.actorId; state = 'awaiting-endpoint-review'
+      } else if (event.action === 'approve') {
+        if (state !== 'awaiting-endpoint-review' || (!policy.allowProposerReview && event.actorId === proposer)) return result(fail('suspended', 'invalid-reviewer'))
+        for (const role of event.roles) {
+          const match = required.find((r) => roleKey(r) === roleKey(role) && r.actorId === event.actorId)
+          if (!match) return result(fail('suspended', 'invalid-reviewer'))
+          approvals.set(roleKey(role), edgeDigest(event))
+        }
+      } else if (event.action === 'accept') {
+        if (state !== 'awaiting-endpoint-review' || event.actorId !== home.actorId || required.some((r) => !approvals.has(roleKey(r)))) return result(fail('suspended', 'missing-reviewer'))
+        state = 'active'
+      } else {
+        if (state === 'draft' || ![home.actorId, proposer, ...endpoints.map((e) => e.stewardId)].includes(event.actorId)) return result(fail('suspended', 'invalid-transition'))
+        state = { reject: 'rejected', suspend: 'suspended', withdraw: 'withdrawn', supersede: 'superseded' }[event.action]
+      }
+      previous = edgeDigest(event); lastTime = Date.parse(event.at)
+    }
+    return result({ state, eligible: state === 'active', assurance: state === 'active' ? 'reviewed-assertion' : 'pending', reviewRefs: [...new Set(approvals.values())].sort() })
+  } catch {
+    // Port errors must not disclose hidden paths, actor details or source bytes.
+    return immutable(fail('suspended', 'verification-unavailable'))
+  }
+}
+
+// Input results must already be authorized for one recipient and evaluated in
+// the same host snapshot. Preserve each complete assertion and its supports.
+export function groupEligibleEdges(results) {
+  const groups = new Map()
+  let binding = null
+  for (const result of results) {
+    if (!decisions.has(result)) throw new Error('unverified edge decision')
+    if (!result.eligible || result.state !== 'active') continue
+    const current = edgeDigest({ bindingId: result.verification.bindingId, policyDigest: result.policyDigest })
+    if (binding !== null && binding !== current) throw new Error('mixed edge decision bindings')
+    binding = current
+    const key = edgeDigest({ family: result.family, triple: result.triple, qualifications: result.qualifications })
+    const group = groups.get(key) ?? { groupId: `edge-group:${key.slice(7)}`, family: result.family, triple: result.triple, assertions: [] }
+    if (group.assertions.some((a) => a.edgeId === result.edgeId && edgeDigest(a) !== edgeDigest(result))) throw new Error('conflicting edge decisions')
+    if (!group.assertions.some((a) => a.edgeId === result.edgeId)) group.assertions.push(structuredClone(result))
+    groups.set(key, group)
+  }
+  return immutable([...groups.values()].map((g) => ({ ...g, assertions: g.assertions.sort((a, b) => a.edgeId.localeCompare(b.edgeId, 'en')) })).sort((a, b) => a.groupId.localeCompare(b.groupId, 'en')))
+}
+
+// Only evaluated decisions may enter this seam; a deserialized eligible flag is
+// never authority. The access host revalidates bindingId/current grants at use.
+export function displayEligibleEdge(result) {
+  if (!decisions.has(result) || !result.eligible || result.state !== 'active') return null
+  return immutable({ edgeId: result.edgeId, source: result.triple.subject, target: result.triple.object,
+    predicate: result.triple.predicate, family: result.family, acceptanceState: result.state, assurance: result.assurance,
+    supportRefs: result.supportRefs.map((s) => s.id), sourceRef: result.supportRefs[0].id, reviewRefs: result.reviewRefs,
+    qualifications: result.qualifications, recordDigest: result.recordDigest, policyDigest: result.policyDigest, verification: result.verification })
+}

package/src/edge-policy/source-citation-adapter.mjs

@@ -0,0 +1,43 @@
+import { canonicalize } from '../attestation/jcs.mjs'
+import { validateRepositoryContribution } from '../graph/repo-contribution.mjs'
+import { validSourceRef } from './contract.mjs'
+
+const need = (value) => { if (!value) throw new TypeError('Invalid source citation input') }
+
+/**
+ * Convert an exact observed occurrence to the policy's raw-byte citation shape.
+ * This pure structural binding does not authenticate source bytes, source-home
+ * custody, freshness or a declared triple. The policy host must still implement
+ * readSource, verifyOrigin and checkSourceHome against its current snapshot.
+ * Original provenance, including UTF16 offsets and any pointer/target range,
+ * stays unchanged in the contribution. Only its outer raw-byte range is cited.
+ * @param {import('../graph/repo-contribution.types.mjs').RepositoryContribution} contribution
+ * @param {import('../graph/repo-contribution.types.mjs').SourceRef} provenance
+ */
+export function sourceCitationFromProvenance(contribution, provenance) {
+  try {
+    need(validateRepositoryContribution(contribution).ok)
+    const { snapshot, repository } = contribution
+    need(provenance?.repoId === repository.repoId && provenance.revision === snapshot.digest)
+    const file = snapshot.files.find((pin) => pin.path === provenance.path)
+    need(file && provenance.digest === file.rawDigest)
+    const { range, rangeDigest } = provenance.locator ?? {}
+    need(range && Number.isSafeInteger(range.byteStart) && range.byteStart >= 0 &&
+      Number.isSafeInteger(range.byteEnd) && range.byteEnd > range.byteStart && range.byteEnd <= file.byteLength)
+    // A matching file pin alone cannot invent a source occurrence. Accept a
+    // detached copy too, while retaining every field of the recorded provenance.
+    const observed = canonicalize(provenance)
+    need([...contribution.ordinaryLinks, ...contribution.declaredRelations]
+      .some((occurrence) => canonicalize(occurrence.provenance) === observed))
+    const citation = {
+      repoId: provenance.repoId, path: provenance.path, revision: provenance.revision,
+      fileDigest: provenance.digest,
+      locator: { byteStart: range.byteStart, byteEnd: range.byteEnd },
+      citedDigest: rangeDigest,
+    }
+    need(validSourceRef(citation))
+    return citation
+  } catch {
+    throw new TypeError('Invalid source citation input')
+  }
+}

package/src/extension-packs/loader.mjs

@@ -468,7 +468,8 @@ export function loadExtensionPacks(project, { report = false, verifyLock = true
 // Explicit registry object, no global state. Bundled resolution keeps its
 // existing id | slug | namespaced affordance; pack protocols resolve by full
 // namespaced id only, so a pack can never shadow or squat a bundled slug.
-export function createProtocolRegistry({ packs = [] } = {}) {
+export function createProtocolRegistry({ packs = [], includeBundled = true } = {}) {
+  if (typeof includeBundled !== 'boolean') throw new TypeError('includeBundled must be a boolean')
   const packProtocols = new Map()
   for (const pack of packs) {
     for (const record of pack.protocols ?? []) packProtocols.set(record.id, record)
@@ -476,14 +477,14 @@ export function createProtocolRegistry({ packs = [] } = {}) {
   return {
     packs,
     protocolById(id) {
-      const bundled = getBundledReadinessProtocol(id)
+      const bundled = includeBundled ? getBundledReadinessProtocol(id) : null
       if (bundled) return bundled
       const record = packProtocols.get(id)
       return record ? record.protocol : null
     },
     listProtocols() {
       return [
-        ...bundledReadinessProtocols,
+        ...(includeBundled ? bundledReadinessProtocols : []),
         ...[...packProtocols.values()].map((record) => record.protocol),
       ]
     },

package/src/extensions/admission.mjs

@@ -0,0 +1,83 @@
+import { canonicalJson, exact, ExtensionError } from './contracts.mjs'
+
+function joinBytes(chunks, size) {
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength }
+  return bytes
+}
+async function cancelResponseBody(body) {
+  if (!body) return
+  let timer
+  try {
+    await Promise.race([
+      Promise.resolve().then(() => body.cancel()).catch(() => {}),
+      new Promise(resolve => { timer = setTimeout(resolve, 100) }),
+    ])
+  } finally { clearTimeout(timer) }
+}
+export async function readInvocationBody(request) {
+  const body = request.body?.getReader()
+  if (!body) throw new ExtensionError('invalid-input')
+  try {
+    let size = 0
+    const chunks = []
+    for (;;) {
+      const { value, done } = await body.read()
+      if (done) break
+      size += value.byteLength
+      if (size > 65536) throw new ExtensionError('invalid-input')
+      chunks.push(value)
+    }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(joinBytes(chunks, size)))
+  } finally { await body.cancel().catch(() => {}) }
+}
+export function createRootAdmissionConsumer(options) {
+  return createAdmissionConsumer(options, options.allowLocalTesting && ['test', 'development'].includes(process.env.NODE_ENV))
+}
+export function createAdmissionConsumer({ origin, fetch: hostFetch = globalThis.fetch }, localTestingAuthorized = false) {
+  const target = new URL(origin)
+  const local = localTestingAuthorized &&
+    target.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(target.hostname)
+  if ((target.protocol !== 'https:' && !local) || target.username || target.password || target.pathname !== '/' || target.search || target.hash) throw new ExtensionError('invalid-input')
+  const endpoint = new URL('/api/root-runtime/extensions/admissions/consume', target)
+  return async (_claims, delegation) => {
+    // Convex supports AbortController and action timers, but not every runtime
+    // implements AbortSignal.timeout. The deadline includes the response body.
+    const controller = new AbortController()
+    let timer, response, reader
+    const expired = new Promise((_, reject) => {
+      timer = setTimeout(() => { controller.abort(); reject(new ExtensionError('unavailable', 503)) }, 5000)
+    })
+    const consume = async () => {
+      response = await hostFetch(endpoint, { method: 'POST', redirect: 'error', signal: controller.signal,
+        headers: { 'content-type': 'application/json' }, body: canonicalJson({ delegation }) })
+      if (response.status === 401 || response.status === 403) return false
+      if (response.status != 200 || response.headers.get('content-type')?.split(';')[0] !== 'application/json') throw new ExtensionError('unavailable', 503)
+      reader = response.body?.getReader()
+      if (!reader) throw new ExtensionError('unavailable', 503)
+      try {
+        let size = 0
+        const chunks = []
+        for (;;) {
+          const { value, done } = await reader.read()
+          if (done) break
+          size += value.byteLength
+          if (size > 1024) throw new ExtensionError('unavailable', 503)
+          chunks.push(value)
+        }
+        const body = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(joinBytes(chunks, size)))
+        exact(body, ['admitted'])
+        if (body.admitted !== true) throw new ExtensionError('unavailable', 503)
+        return true
+      } catch { throw new ExtensionError('unavailable', 503) }
+    }
+    try { return await Promise.race([consume(), expired]) } finally {
+      clearTimeout(timer)
+      // Also close refusal/error responses, whose body reader was never acquired.
+      // Abort first; a broken/custom stream cancellation cannot extend transport.
+      controller.abort()
+      await cancelResponseBody(reader ?? response?.body)
+    }
+  }
+}

package/src/extensions/client.d.mts

@@ -0,0 +1,23 @@
+import type { ExtensionReleaseBundle, ExtensionReleaseRegistration, ExtensionManifest, InstallationBinding, Invocation, Json, OperationReceipt } from './contracts.mjs'
+export interface HostTransport {
+  getInstallation(id: string): Promise<InstallationBinding>;
+  invoke(request: Invocation): Promise<OperationReceipt>;
+  lookupOperation(id: string, key: string, action: string): Promise<OperationReceipt | null>;
+  recoverOperation(binding: InstallationBinding, key: string, action: string): Promise<OperationReceipt>;
+  recordResult(operationId: string): Promise<void>;
+}
+export interface AdminHostTransport {
+  registerRelease?(bundle: ExtensionReleaseBundle): Promise<ExtensionReleaseRegistration>;
+  configure(manifest: ExtensionManifest, connectionRef: string, environment: 'development' | 'staging' | 'production'): Promise<InstallationBinding>;
+  transition(binding: InstallationBinding, transition: 'verify' | 'enable' | 'disable' | 'remove'): Promise<InstallationBinding>;
+  upgrade(binding: InstallationBinding, manifest: ExtensionManifest): Promise<InstallationBinding>;
+}
+export function createHttpHostTransport(hostFetch: typeof fetch): HostTransport & AdminHostTransport
+export function createExtensionClient(transport: HostTransport): {
+  getInstallation(id: string): Promise<InstallationBinding>;
+  invoke(binding: InstallationBinding, actionId: string, input: Json, idempotencyKey: string): Promise<OperationReceipt>;
+  lookupOperation(id: string, key: string, action: string): Promise<OperationReceipt | null>;
+  recoverOperation(binding: InstallationBinding, key: string, action: string): Promise<OperationReceipt>;
+  recordResult(operationId: string): Promise<void>;
+}
+export function createExtensionAdminClient(transport: AdminHostTransport): Omit<AdminHostTransport, 'configure' | 'registerRelease'> & { registerRelease(bundle: ExtensionReleaseBundle): Promise<ExtensionReleaseRegistration>; configure(manifest: ExtensionManifest, connectionRef: string, environment?: 'development' | 'staging' | 'production'): Promise<InstallationBinding> }