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

package/src/projection/obsidian/materialize/redaction.mjs

@@ -0,0 +1,327 @@
+import { identityLineTexts } from '../contracts.mjs'
+import { refuse } from './byte-lens.mjs'
+
+// The redaction guard: the last check before a prepared view is returned. It
+// judges the assembled result, every note included, whether the note was
+// emitted on this call or reused from the preparation cache, and refuses the
+// view with `redaction-failure`, naming the in-view note (or file) and the
+// rule, never the value. See "The redaction guard" in docs/obsidian-contract.md.
+//
+//   allow-list  every path the emitter wrote (note and attachment paths,
+//               rewritten link and embed targets, link targets in generated
+//               regions) is one allocated to this view, and each identity
+//               block names exactly its own note
+//   deny-list   the free text of the generated regions, read as a reader
+//               sees it, names no unambiguous identifier of anything the
+//               audience may not see (refused); an ambiguous one, and any
+//               identifier of what the audience may see but the view does
+//               not select, is reported
+//   coverage    both run over every note of the view
+//
+// REDACTION_RULES are the rules production uses. The mutation controls in
+// test/obsidian-materialization.test.mjs replace one at a time through
+// createViewPreparationForOracleTests to prove each is load-bearing.
+
+const EXT = 'mnstry.atelier.obsidian'
+const RELATIONS_HEADING_LINE = '## Relations (generated)'
+const RELATIONS_NOTE_LINE = '%% Generated from the canonical graph. Edits to this section are not applied to any source. %%'
+const RELATION_OUT = /^- [a-z_]+ → \[\[([^[\]|]*)\|(.*)\]\]$/
+const RELATION_IN = /^- [a-z_]+ ← (.*)$/
+const OUTSIDE_COUNT = /^Relationships leading outside this view: [0-9]+$/
+const ORIGINAL_LINK = /^- Original: \[\[([^[\]|]*)\|Open the original file\]\]$/
+const EMBED_LINE = /^!\[\[([^[\]|]*)\]\]$/
+// Every link a generated region holds: a wikilink or embed not escaped by a
+// backslash, and a Markdown link target. Generated free text escapes `[`, `]`
+// and `|`, so only links the emitter wrote remain.
+const GENERATED_WIKILINK = /(?<!\\)!?\[\[([^[\]\n]*?)\]\]/g
+const GENERATED_MARKDOWN_LINK = /(?<!\\)\]\(([^()\n]*)\)/g
+
+const linesOf = (text) => text.split('\n').map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line))
+
+// Generated prose escapes Markdown punctuation with a backslash (see plainText
+// in prepare-view.mjs). A reader sees the text without those backslashes, and
+// the deny-list reads it the same way.
+const ESCAPED = /\\([\\`*_[\]<>#|^$%~=!&])/g
+const asRead = (text) => text.replace(ESCAPED, '$1')
+
+// An identity or a path matches only as a whole token, never inside a longer
+// one. A letter or digit beside the match, or one of `. _ : / -` joined to a
+// letter or digit beside it, continues the token; sentence punctuation after
+// it (a full stop, a colon before a space) does not.
+const ALNUM = /^[\p{L}\p{N}]$/u
+const JOINERS = new Set(['.', '_', ':', '/', '-'])
+
+function codePointAt(text, index) {
+  if (index < 0 || index >= text.length) return ''
+  const code = text.codePointAt(index)
+  // A low surrogate is the second half of the character before it.
+  if (code >= 0xdc00 && code <= 0xdfff && index > 0) return String.fromCodePoint(text.codePointAt(index - 1))
+  return String.fromCodePoint(code)
+}
+const isAlnumAt = (text, index) => ALNUM.test(codePointAt(text, index))
+const continuesAfter = (text, end) => isAlnumAt(text, end) || (JOINERS.has(text[end]) && isAlnumAt(text, end + 1))
+const continuesBefore = (text, start) => isAlnumAt(text, start - 1) || (JOINERS.has(text[start - 1]) && isAlnumAt(text, start - 2))
+
+const REFUSE = 3
+const DIAGNOSE = 2
+const NOTICE = 1
+const UNITS = 0x10000
+
+// One Aho–Corasick automaton over every value, read in UTF-16 code units, with
+// the token boundary tested at each hit: building it is linear in the values,
+// and a text is read once, whatever their number. `refuse` values refuse a
+// view; `diagnose` and `notice` values are reported, each under its own code.
+// The matcher answers the strongest of what a text holds ('refuse', 'diagnose',
+// 'notice' or null). Values and texts are compared in NFC.
+export function createDenyMatcher({ refuse: refused = [], diagnose = [], notice = [] } = {}) {
+  const next = new Map()
+  const parent = [0]
+  const unit = [0]
+  const depth = [0]
+  const output = [null]
+  const add = (raw, strength) => {
+    if (typeof raw !== 'string' || raw === '') return
+    const value = raw.normalize('NFC')
+    let state = 0
+    for (let index = 0; index < value.length; index += 1) {
+      const key = state * UNITS + value.charCodeAt(index)
+      let child = next.get(key)
+      if (child === undefined) {
+        child = parent.length
+        next.set(key, child)
+        parent.push(state)
+        unit.push(value.charCodeAt(index))
+        depth.push(depth[state] + 1)
+        output.push(null)
+      }
+      state = child
+    }
+    if (output[state] === null) output[state] = { length: value.length, strength }
+    else output[state].strength = Math.max(output[state].strength, strength)
+  }
+  for (const value of refused) add(value, REFUSE)
+  for (const value of diagnose) add(value, DIAGNOSE)
+  for (const value of notice) add(value, NOTICE)
+  // Failure and output links, state by state in order of depth.
+  const fail = new Int32Array(parent.length)
+  const outputLink = new Int32Array(parent.length).fill(-1)
+  const byDepth = []
+  for (let state = 1; state < parent.length; state += 1) (byDepth[depth[state]] ??= []).push(state)
+  for (const states of byDepth) {
+    for (const state of states ?? []) {
+      let target = 0
+      if (parent[state] !== 0) {
+        let from = fail[parent[state]]
+        while (from !== 0 && !next.has(from * UNITS + unit[state])) from = fail[from]
+        target = next.get(from * UNITS + unit[state]) ?? 0
+      }
+      fail[state] = target
+      outputLink[state] = output[target] !== null ? target : outputLink[target]
+    }
+  }
+  return function match(raw) {
+    const text = String(raw).normalize('NFC')
+    let state = 0
+    let found = 0
+    for (let index = 0; index < text.length; index += 1) {
+      const code = text.charCodeAt(index)
+      while (state !== 0 && !next.has(state * UNITS + code)) state = fail[state]
+      state = next.get(state * UNITS + code) ?? 0
+      for (let hit = output[state] !== null ? state : outputLink[state]; hit > 0; hit = outputLink[hit]) {
+        const { length, strength } = output[hit]
+        if (strength <= found || continuesBefore(text, index - length + 1) || continuesAfter(text, index + 1)) continue
+        found = strength
+        if (found === REFUSE) return 'refuse'
+      }
+    }
+    return found === REFUSE ? 'refuse' : found === DIAGNOSE ? 'diagnose' : found === NOTICE ? 'notice' : null
+  }
+}
+
+// What one generated region of one note says: the link targets it holds and
+// its free text, the author's words that reached it. A line that is not one
+// of the shapes the emitter writes is free text as a whole.
+function readGeneratedRegion({ kind, text, fence, own }) {
+  const links = [...text.matchAll(GENERATED_WIKILINK)].map((match) => match[1].split('|')[0].split('#')[0])
+    .concat([...text.matchAll(GENERATED_MARKDOWN_LINK)].map((match) => match[1]))
+  const freeText = []
+  for (const line of linesOf(text)) {
+    if (line === '' || line === fence) continue
+    if (kind === 'representation') {
+      if (line.startsWith('# ')) freeText.push(line.slice(2))
+      else if (line === own.format || line === own.source || ORIGINAL_LINK.test(line) || EMBED_LINE.test(line)) continue
+      else if (line.startsWith('- Tags: ')) freeText.push(line.slice('- Tags: '.length))
+      else freeText.push(line)
+      continue
+    }
+    if (line === RELATIONS_HEADING_LINE || line === RELATIONS_NOTE_LINE || OUTSIDE_COUNT.test(line)) continue
+    const outgoing = RELATION_OUT.exec(line)
+    if (outgoing) { freeText.push(outgoing[2]); continue }
+    const incoming = RELATION_IN.exec(line)
+    if (incoming) { freeText.push(incoming[1]); continue }
+    freeText.push(line.replace(GENERATED_WIKILINK, ' '))
+  }
+  return { links, freeText: freeText.map(asRead) }
+}
+
+// Whether an identity region holds exactly the identity lines of its own note
+// and nothing but the front-matter delimiters, the comment delimiters of the
+// end-of-note placement, blank lines and a fence closure around them.
+function identityRegionIsOwn(text, node, fence) {
+  const expected = identityLineTexts(node)
+  const lines = linesOf(text)
+  const named = lines.filter((line) => line.startsWith('atelier-'))
+  if (named.length !== expected.length || named.some((line, index) => line !== expected[index])) return false
+  return lines.every((line) => named.includes(line) || line === '' || line === '---' || line === '%%' || (fence !== null && line === fence))
+}
+
+// Everything the rules judge about one note, read once.
+export function readNoteForRedaction({ note, bytes, node, own }) {
+  const regions = []
+  for (const region of note.regions.generated) {
+    if (region.kind === 'identity') continue
+    const fence = region.ext?.[EXT]?.fenceClosure?.fence ?? null
+    regions.push(readGeneratedRegion({ kind: region.kind, text: bytes.subarray(region.range.start, region.range.end).toString('utf8'), fence, own }))
+  }
+  const identity = note.regions.identity
+  const identityRegion = note.regions.generated.find((region) => region.kind === 'identity')
+  const identityFence = identityRegion?.ext?.[EXT]?.fenceClosure?.fence ?? null
+  return {
+    note,
+    links: regions.flatMap((region) => region.links),
+    freeText: regions.flatMap((region) => region.freeText),
+    identity: identity === undefined ? null : { own: identityRegionIsOwn(bytes.subarray(identity.start, identity.end).toString('utf8'), node, identityFence) },
+  }
+}
+
+// A refusal names the rule and the in-view note (or file) it concerns, never
+// the value: `where` is a path allocated to this view, or null when the only
+// path at hand is the one in question.
+const refuseAt = (rule, where, message) => refuse('redaction-failure', where === null ? `${message} (${rule})` : `${message} (${rule}, ${where})`,
+  { rule, ...(where === null ? {} : where.endsWith('.md') ? { notePath: where } : { filePath: where }) })
+
+// Rule 1. `view.allocatedPathOf(nodeId)` is the path allocated to a node of
+// this view (null for any other), `view.attachments` the files it holds and
+// `view.linkTargets` every spelling a rewritten or generated link of this
+// view may use.
+function allowList({ manifest, notes, read, view, layoutVersion }) {
+  const judgedIds = new Set(notes.map((note) => note.nodeId))
+  const pathOfNode = new Map(manifest.notes.map((note) => [note.nodeId, note.path]))
+  for (const note of notes) {
+    if (view.allocatedPathOf(note.nodeId) !== note.path) refuseAt('allow-list', view.allocatedPathOf(note.nodeId), 'a note path is not the one allocated to a note of this view')
+    for (const embed of note.ext?.[EXT]?.assetEmbeds ?? []) {
+      if (!view.attachments.has(embed.attachment)) refuseAt('allow-list', note.path, 'an embed names a file that is not part of this view')
+    }
+  }
+  for (const attachment of manifest.attachments) {
+    if (!view.attachments.has(attachment.path)) refuseAt('allow-list', null, 'an attachment is not a file of this view')
+  }
+  for (const link of manifest.links.filter((item) => judgedIds.has(item.sourceNodeId))) {
+    for (const inversion of link.inversions ?? []) checkInversion(inversion, pathOfNode.get(link.sourceNodeId), view)
+  }
+  for (const note of notes) {
+    for (const embed of note.ext?.[EXT]?.assetEmbeds ?? []) for (const inversion of embed.inversions) checkInversion(inversion, note.path, view)
+  }
+  for (const entry of read) {
+    for (const target of entry.links) if (!view.linkTargets.has(target)) refuseAt('allow-list', entry.note.path, 'a generated link names a file that is not part of this view')
+    if (layoutVersion >= 2 && (entry.identity === null || !entry.identity.own)) refuseAt('identity-block', entry.note.path, 'an identity block does not name exactly its own note')
+  }
+}
+
+function checkInversion(inversion, notePath, view) {
+  const ext = inversion.ext?.[EXT] ?? {}
+  const emitted = Buffer.from(ext.emitted ?? '', 'base64url').toString('utf8')
+  // The words an author chose, appended after a rewritten wikilink target: authored bytes, not a path.
+  if ((ext.original ?? '') === '' && emitted.startsWith('|')) return
+  if (!view.linkTargets.has(emitted)) refuseAt('allow-list', notePath, 'an emitted link names a file that is not part of this view')
+}
+
+// Rule 2. A refused value refuses the view and names the note whose generated
+// region holds it; a reported one is recorded through `report`, once a note
+// and code, and the view goes on: an ambiguous identifier of what the audience
+// may not see (a bare word, a root file name) as bare-identity-in-generated-text,
+// an identifier of what the audience may see but the view does not select as
+// unselected-identity-in-generated-text.
+const REPORTED = { diagnose: 'bare-identity-in-generated-text', notice: 'unselected-identity-in-generated-text' }
+
+function denyList({ read, deny, report }) {
+  for (const entry of read) {
+    const reported = new Set()
+    for (const text of entry.freeText) {
+      const found = deny(text)
+      if (found === 'refuse') refuseAt('deny-list', entry.note.path, 'generated text names an identity that is not part of this view')
+      const code = REPORTED[found]
+      if (code !== undefined && !reported.has(code)) {
+        reported.add(code)
+        report({ code, rule: 'deny-list', repoId: entry.note.repoId, nodeId: entry.note.nodeId, notePath: entry.note.path })
+      }
+    }
+  }
+}
+
+export const REDACTION_RULES = Object.freeze({
+  // Rule 3: which notes the other rules judge. Every note of the view.
+  judged: ({ notes }) => notes,
+  allowList,
+  denyList,
+})
+
+// Returns what rule 2 reported.
+export function assertViewRedaction({ manifest, files, reused, nodeOf, ownOf, view, deny, layoutVersion }, rules = REDACTION_RULES) {
+  const notes = rules.judged({ notes: manifest.notes, reused })
+  const byPath = new Map(files.map((file) => [file.path, file.bytes]))
+  const read = notes.map((note) => readNoteForRedaction({ note, bytes: byPath.get(note.path), node: nodeOf(note.nodeId), own: ownOf(note.nodeId) }))
+  const reported = []
+  rules.allowList({ manifest, notes, read, view, layoutVersion })
+  rules.denyList({ read, deny, report: (item) => reported.push(item) })
+  return reported
+}
+
+// Layout 1 only, as the earlier release checked it. Two rules, because the two
+// kinds of bytes differ: a substring the emitter itself produced from an
+// allocated path (note and attachment paths, rewritten link targets) may name
+// only a note or asset of this view; free text in a generated region (titles,
+// tags, source paths, which are the author's words) is refused only when it
+// names an identity of the census that is outside this view. Author text that
+// merely looks like an identity suffix, such as a content-hashed asset name,
+// is not a redaction failure.
+export function assertOnlyVaultIdentities({ manifest, files, vaultSuffixes, forbiddenSuffixes }) {
+  const index = (suffixes) => {
+    const byPrefix = new Map()
+    for (const full of suffixes) byPrefix.set(full.slice(0, 12), [...(byPrefix.get(full.slice(0, 12)) ?? []), full])
+    return (suffix) => (byPrefix.get(suffix.slice(0, 12)) ?? []).some((full) => full.startsWith(suffix))
+  }
+  const allowed = index(vaultSuffixes)
+  const forbidden = index(forbiddenSuffixes)
+  const suffixesIn = (text) => [...text.matchAll(/--([0-9a-f]{12,64})(?![0-9a-f])/g)].map((match) => match[1])
+  // An emitted path ends in the allocated suffix (before the extension); the
+  // readable part before it is the author's title and may look like anything.
+  // A wikilink rewrite may append `|<the author's own words>`; only the part
+  // before the first `|` is an emitted path.
+  const checkEmitted = (text) => {
+    for (const segment of text.split('|')[0].split('#')[0].split('/')) {
+      const trailing = /--([0-9a-f]{12,64})(?:\.[^./]+)?$/.exec(segment)
+      if (trailing && !allowed(trailing[1])) refuse('redaction-failure', 'an emitted path names a note that is not part of this view')
+    }
+    for (const suffix of suffixesIn(text)) if (forbidden(suffix)) refuse('redaction-failure', 'an emitted path names a note that is not part of this view')
+  }
+  const checkText = (text) => {
+    for (const suffix of suffixesIn(text)) if (forbidden(suffix)) refuse('redaction-failure', 'generated output names a note that is not part of this view')
+  }
+  const byPath = new Map(files.map((file) => [file.path, file.bytes]))
+  for (const note of manifest.notes) {
+    const bytes = byPath.get(note.path)
+    for (const region of note.regions.generated) checkText(bytes.subarray(region.range.start, region.range.end).toString('utf8'))
+  }
+  for (const link of manifest.links) {
+    for (const inversion of link.inversions ?? []) checkEmitted(Buffer.from(inversion.ext[EXT].emitted, 'base64url').toString('utf8'))
+  }
+  for (const note of manifest.notes) {
+    for (const embed of note.ext[EXT].assetEmbeds ?? []) {
+      checkEmitted(embed.attachment)
+      for (const inversion of embed.inversions) checkEmitted(Buffer.from(inversion.ext[EXT].emitted, 'base64url').toString('utf8'))
+    }
+  }
+  for (const note of manifest.notes) checkEmitted(note.path)
+  for (const attachment of manifest.attachments) checkEmitted(attachment.path)
+}

package/src/projection/obsidian/materialize/settings.mjs

@@ -1,55 +1,134 @@
+import { ObsidianContractRefusal } from '../contracts.mjs'
+import { PLUGIN_DATA_FILE, PLUGIN_DIRECTORY, PLUGIN_ID, PLUGIN_SOURCE_FILES } from '../plugin-bridge/channel.mjs'
 import { refuse, sha256Digest } from './byte-lens.mjs'
 
-// Policy-owned Obsidian settings. Atelier owns exactly two keys of one file:
-// the built-in Sync and Publish core plugins stay disabled, because a generated
-// view must not leave the machine through the editor. Every other path under
-// the settings directory, and every other key of that file, belongs to the
-// person using the vault and is never prepared, replaced or removed here.
+// Policy-owned Obsidian settings. Atelier owns exactly these, and nothing
+// else under the settings directory:
+//
+//   core-plugins.json          two keys: the built-in Sync and Publish core
+//                              plugins stay disabled, because a generated view
+//                              must not leave the machine through the editor
+//   community-plugins.json     one entry: Atelier's own plugin is enabled
+//   plugins/atelier-projection/{manifest.json,main.js,styles.css,data.json}
+//                              Atelier's own plugin, whole files
+//
+// Every other path under the settings directory, every other key of
+// core-plugins.json and every other entry of community-plugins.json belongs to
+// the person using the vault and is never prepared, replaced or removed here.
+// The two settings files are merged with the bytes on disk when they are
+// published; the plugin files are Atelier's bytes and their digests are pinned
+// in the generation manifest.
+//
+// The community entry is Atelier's only while the person wants the plugin in
+// that vault. The caller says so per view (see plugin-choice.mjs): the list is
+// then prepared from the exact bytes it held when that was decided, and it is
+// published only over exactly those bytes; or the list is withheld and never
+// touched.
 
 export const SETTINGS_ROOT = '.obsidian'
 export const POLICY_SETTINGS_PATH = `${SETTINGS_ROOT}/core-plugins.json`
 export const POLICY_DISABLED_CORE_PLUGINS = Object.freeze(['publish', 'sync'])
+export const COMMUNITY_PLUGINS_PATH = `${SETTINGS_ROOT}/community-plugins.json`
+export const POLICY_ENABLED_COMMUNITY_PLUGINS = Object.freeze([PLUGIN_ID])
+export const POLICY_SETTINGS_PATHS = Object.freeze([POLICY_SETTINGS_PATH, COMMUNITY_PLUGINS_PATH])
+export const PLUGIN_OWNED_PATHS = Object.freeze([...PLUGIN_SOURCE_FILES, PLUGIN_DATA_FILE].map((name) => `${PLUGIN_DIRECTORY}/${name}`))
 
 export function isPolicySettingsPath(relativePath) {
-  return relativePath === POLICY_SETTINGS_PATH
+  return POLICY_SETTINGS_PATHS.includes(relativePath)
+}
+
+export function isPluginOwnedPath(relativePath) {
+  return PLUGIN_OWNED_PATHS.includes(relativePath)
 }
 
 export function isUserOwnedSettingsPath(relativePath) {
-  return (relativePath === SETTINGS_ROOT || relativePath.startsWith(`${SETTINGS_ROOT}/`)) && !isPolicySettingsPath(relativePath)
+  return (relativePath === SETTINGS_ROOT || relativePath.startsWith(`${SETTINGS_ROOT}/`)) && !isPolicySettingsPath(relativePath) && !isPluginOwnedPath(relativePath)
 }
 
 const serialize = (value) => Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8')
 
-// `existing` is the current bytes of the policy file when the vault already
-// has one, so keys the person set survive. Bytes that already satisfy the
-// policy are returned untouched.
-export function prepareSettings({ existing = null } = {}) {
-  let bytes
-  if (existing === null || existing === undefined) {
-    bytes = serialize(Object.fromEntries(POLICY_DISABLED_CORE_PLUGINS.map((id) => [id, false])))
-  } else {
-    if (!Buffer.isBuffer(existing)) refuse('invalid-settings', 'existing settings must be supplied as a Buffer')
-    let current
-    try {
-      current = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(existing))
-    } catch {
-      refuse('invalid-settings', 'existing core plugin settings do not parse; they are left alone')
-    }
-    if (Array.isArray(current)) {
-      // Older list form: membership means enabled.
-      const kept = current.filter((id) => !POLICY_DISABLED_CORE_PLUGINS.includes(id))
-      bytes = kept.length === current.length ? existing : serialize(kept)
-    } else if (current !== null && typeof current === 'object') {
-      const satisfied = POLICY_DISABLED_CORE_PLUGINS.every((id) => current[id] === false)
-      bytes = satisfied ? existing : serialize({ ...current, ...Object.fromEntries(POLICY_DISABLED_CORE_PLUGINS.map((id) => [id, false])) })
-    } else {
-      refuse('invalid-settings', 'existing core plugin settings have an unknown shape; they are left alone')
-    }
+function parseExisting(existing, label) {
+  if (!Buffer.isBuffer(existing)) refuse('invalid-settings', 'existing settings must be supplied as a Buffer')
+  try {
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(existing))
+  } catch {
+    return refuse('invalid-settings', `existing ${label} do not parse; they are left alone`)
+  }
+}
+
+// core-plugins.json: the owned keys set to false, every other key kept.
+function coreCandidate(existing) {
+  if (existing === null || existing === undefined) return serialize(Object.fromEntries(POLICY_DISABLED_CORE_PLUGINS.map((id) => [id, false])))
+  const current = parseExisting(existing, 'core plugin settings')
+  if (Array.isArray(current)) {
+    // Older list form: membership means enabled.
+    const kept = current.filter((id) => !POLICY_DISABLED_CORE_PLUGINS.includes(id))
+    return kept.length === current.length ? existing : serialize(kept)
+  }
+  if (current !== null && typeof current === 'object') {
+    const satisfied = POLICY_DISABLED_CORE_PLUGINS.every((id) => current[id] === false)
+    return satisfied ? existing : serialize({ ...current, ...Object.fromEntries(POLICY_DISABLED_CORE_PLUGINS.map((id) => [id, false])) })
+  }
+  return refuse('invalid-settings', 'existing core plugin settings have an unknown shape; they are left alone')
+}
+
+// community-plugins.json: the list of enabled plugins, in the person's order,
+// with Atelier's own appended when it is missing.
+function communityCandidate(existing) {
+  if (existing === null || existing === undefined) return serialize([...POLICY_ENABLED_COMMUNITY_PLUGINS])
+  const current = parseExisting(existing, 'community plugin settings')
+  if (!Array.isArray(current)) refuse('invalid-settings', 'existing community plugin settings are not a list; they are left alone')
+  const missing = POLICY_ENABLED_COMMUNITY_PLUGINS.filter((id) => !current.includes(id))
+  return missing.length === 0 ? existing : serialize([...current, ...missing])
+}
+
+const CANDIDATES = Object.freeze({ [POLICY_SETTINGS_PATH]: coreCandidate, [COMMUNITY_PLUGINS_PATH]: communityCandidate })
+const OWNED = Object.freeze({ [POLICY_SETTINGS_PATH]: { ownedKeys: [...POLICY_DISABLED_CORE_PLUGINS] }, [COMMUNITY_PLUGINS_PATH]: { ownedEntries: [...POLICY_ENABLED_COMMUNITY_PLUGINS] } })
+
+// The bytes one policy settings file should hold, given its bytes on disk now.
+// Bytes that already satisfy the policy are returned untouched.
+export function preparePolicySettingsFile(relativePath, existing = null) {
+  if (!isPolicySettingsPath(relativePath)) refuse('invalid-settings', 'only a policy settings file is prepared here')
+  const bytes = CANDIDATES[relativePath](existing)
+  return { path: relativePath, kind: 'settings', bytes, digest: sha256Digest(bytes) }
+}
+
+// The community plugin list as it will be published from the bytes it held
+// when the decision was made. `expectedDigest` binds the publication to those
+// bytes (null: to the file being absent). A list whose shape the policy does
+// not know is left alone when it is published; its own bytes stand for it here.
+function prepareCommunityFile(existing) {
+  let file
+  try { file = preparePolicySettingsFile(COMMUNITY_PLUGINS_PATH, existing) } catch (error) {
+    if (!(error instanceof ObsidianContractRefusal) || existing === null) throw error
+    file = { path: COMMUNITY_PLUGINS_PATH, kind: 'settings', bytes: existing, digest: sha256Digest(existing) }
+  }
+  return { ...file, expectedDigest: existing === null ? null : sha256Digest(existing) }
+}
+
+// `existing` is the current bytes of core-plugins.json when the vault already
+// has one, so keys the person set survive. `plugin`, when given, is Atelier's
+// plugin for this vault (preparePluginFiles): its files are carried and their
+// digests are pinned. `plugin.community` says what happens to its entry:
+//
+//   absent                                  the entry is offered; the list is merged with the bytes on disk when published
+//   { entry: 'owned', existing: bytes|null }  the entry is owned; the list is prepared from these bytes and published only over them
+//   { entry: 'withheld', reason }           the list is not carried at all: the person turned the plugin off, or it cannot be read
+export function prepareSettings({ existing = null, plugin = null } = {}) {
+  if (plugin !== null && (!Array.isArray(plugin.files) || plugin.files.some((file) => file.kind !== 'plugin' || !isPluginOwnedPath(file.path)))) {
+    refuse('invalid-settings', 'plugin files must be Atelier\'s own plugin files')
+  }
+  const community = plugin?.community ?? null
+  if (community !== null && !((community.entry === 'owned' && (community.existing === null || Buffer.isBuffer(community.existing))) || community.entry === 'withheld')) {
+    refuse('invalid-settings', 'the community entry is owned from known bytes, or withheld')
   }
+  const listed = plugin === null ? [] : community === null ? [preparePolicySettingsFile(COMMUNITY_PLUGINS_PATH, null)] : community.entry === 'owned' ? [prepareCommunityFile(community.existing)] : []
+  const settings = [preparePolicySettingsFile(POLICY_SETTINGS_PATH, existing), ...listed]
   return {
-    files: [{ path: POLICY_SETTINGS_PATH, kind: 'settings', bytes, digest: sha256Digest(bytes) }],
+    files: [...settings, ...(plugin === null ? [] : plugin.files)],
     ownership: {
-      policyOwned: [{ path: POLICY_SETTINGS_PATH, ownedKeys: [...POLICY_DISABLED_CORE_PLUGINS], digest: sha256Digest(bytes), byteLength: bytes.length }],
+      policyOwned: settings.map((file) => ({ path: file.path, ...OWNED[file.path], digest: file.digest, byteLength: file.bytes.length, ...(Object.hasOwn(file, 'expectedDigest') ? { expectedDigest: file.expectedDigest } : {}) })),
+      ...(plugin === null ? {} : { pluginOwned: { ...plugin.ownership, entry: community?.entry === 'withheld' ? 'withheld' : 'owned', ...(community?.entry === 'withheld' ? { withheldBecause: String(community.reason ?? 'unstated') } : {}) } }),
       userOwnedRoot: SETTINGS_ROOT,
       rule: 'every-other-path-and-key-is-user-owned',
     },