@mnstry/atelier 0.2.0-alpha.14 → 0.2.0-alpha.16

package/src/commands/ingest.mjs

@@ -9,7 +9,7 @@ ignored .atelier-local/ state. Plans bind explicit sources, scope and budgets.
 Run processes bounded local text, CSV and JSON. Status retains every selected
 source's disposition. Query returns source-bound lexical evidence with coverage;
 no operation accepts semantic claims, calls a provider or enrolls raw files into
-the graph. Output is private JSON. See docs/ingestion.md.`
+the graph. Output is private JSON. See docs/guides/ingestion.md.`
 
 try {
   const command = process.argv[2]

package/src/commands/learn.mjs

@@ -17,7 +17,7 @@ lesson digest. Activate makes approved content available to a named harness;
 it does not install files or grant tool permissions. Withdraw stops future use.
 List, context, render, graph, export and plan print private JSON to stdout.
 Export is an explicit private archive, never a send or publication operation.
-See docs/learning.md for complete examples.`
+See docs/guides/learning.md for complete examples.`
 
 function exactObject(value, allowed, required) {
   if (!value || typeof value !== 'object' || Array.isArray(value)

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'
@@ -115,7 +115,7 @@ export const USAGE = `Usage: atelier obsidian <operation> [--project atelier.pro
 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, none by default.
+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
@@ -383,7 +383,7 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
     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 }) : () => resolveProjectConfig({ argv: configFlag === undefined ? [] : [`--project=${path.resolve(cwd, configFlag)}`], cwd, env, writeLocalState: false }))
+    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
@@ -470,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()
@@ -482,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) }
     }
@@ -632,7 +632,7 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
       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
@@ -657,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)
@@ -693,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,
@@ -901,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.
@@ -1090,8 +1099,10 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
       // again, then the proven service stops. Everything a person made or may want back stays, and is named.
       async uninstall() {
         const project = (locateProject ?? loadProject)()
-        let workspace = null
-        try { const found = resolveServiceWorkspace({ project, dataRoot, env, platform }); workspace = found?.workspaceRoot ? found : null } catch (error) { if (!isTyped(error)) throw error }
+        // 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)
@@ -1099,7 +1110,7 @@ export async function runObsidianCommandForOracleTests(options = {}, rules = {})
         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 } },
@@ -1111,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> }