create-pmos 0.52.0 → 0.53.0

package/workspace/lib/placements.js

@@ -0,0 +1,440 @@
+'use strict';
+/* placements.js — THE ONE WRITER and THE ONE FOLD of placements.jsonl: where each initiative sits on the Roadmap
+ * (Now, Next, Later), in what order, and its check-by date (pm-os-absorb, PRD R20 A, R23, R24, R26; D86).
+ *
+ *   readPlacements(root, { now, rules, records }) → {
+ *     ok: true,
+ *     byInit: { [id]: { horizon: 'now'|'next'|'later', rank, after, check_by, confirmed, dormant, source } },
+ *     order: { now: [id…], next: [id…], later: [id…] },          ranked, first is top
+ *     proposals: [{ eid, init, horizon, after, by, at }],        agent lines (proposed:true) not yet adopted or dropped
+ *     moves: [{ init, from, to, at, by, via }],                  every horizon change, oldest first
+ *     flags: [{ kind, eid, init, why }],
+ *   }
+ *   horizonOf(result, id)                        → the initiative's horizon; 'later' when it has no placement
+ *   appendFromUi(root, events, { actor, now })   → { ok, written, lines } | { ok: false, status, error, index }
+ *   appendFromCli(root, events, { actor, now })  → the same
+ *
+ * `records` is the list of workflow rows ({ id, lane, last_activity, accepted, stopped, group? }, scripts/workflow-state.js
+ * --json) the day-one derivation (R26) reads; `rules` is lib/plan-rules.js readRules(root). A consumer that needs a
+ * horizon reads it through horizonOf, never from the file.
+ *
+ * The actor is never chosen by the caller of a route: the route takes it from pm-guard.js (Move to Now, adopt — PM
+ * only) or actor.js (every other press); the CLI from actor.fromCli or requirePmCli. Only a PM line moves an initiative
+ * into Now; an agent's line is a proposal (`proposed: true`), whatever horizon it names.
+ *
+ * THE `placed` LINE (the shared contract; 2C may add events, never change this one):
+ *   { v: 1, eid, ev: 'placed', initiative, horizon: 'now'|'next'|'later', after: <initiative id> | null,
+ *     check_by?: 'YYYY-MM-DD' | null, proposed?: true, by, via, at }
+ * `after: null` is the top of the horizon; an `after` that is not in that horizon puts it at the end. A line without
+ * `check_by` keeps the previous one; `check_by: null` clears it. A `proposed` line moves nothing: it is a proposal.
+ *
+ * THE EVENTS 2C ADDED (each with the same envelope):
+ *   { ev: 'created', initiative, from?: 'capture-YYYY-MM-DD-<n>' }   the initiative writer's landing line: top of
+ *        Later, so a new record never reads Now through day one (R16, R23: what an agent creates lands in Later).
+ *        Any actor; only for an initiative with no line yet. `from` names the capture it came from (triage reads it).
+ *   { ev: 'adopted', proposal: <eid> }   the PM keeps an agent's proposal: its placement applies as the PM's.
+ *   { ev: 'dropped', proposal: <eid> }   the proposal is closed unapplied (the PM, or the agent that proposed it).
+ *   pmOnly(rec) → true for a line only the PM may write: a non-proposed `placed` into Now, and `adopted`. The checker
+ *                 (scripts/check-pm-lines.js, 2B) asks this function and never reads the schema itself.
+ *
+ * DAY ONE (R26), with no migration. An initiative of a work lane with no line in the ledger is placed by its activity:
+ * active within `stall_days` reads Now, unconfirmed (`confirmed: false`, `source: 'day-one'`, outside any cap); every
+ * other one reads Later, newest activity first. Day one's rows are seeded into their horizon before the ledger lines
+ * apply: a line with `after: null` goes above them, and a line whose `after` names a day-one row lands right after it
+ * (the page and the CLI send `after` from the displayed order). A finished initiative (accepted, or stopped by a lifecycle line) never
+ * reads Now: it leaves Now by itself (R3) and goes to the end of Later. In Later, an initiative untouched for
+ * `dormant_days` is `dormant: true` (the page folds it behind "N dormant"). Without `records` there is no day one and no
+ * lane filter: the fold answers the ledger alone.
+ *
+ * WORK LANES ONLY (D86 point 4). With `records`, an initiative whose lane is not in the `work` group of
+ * scripts/lane-defs.js (read through the engine's lanesFor, never a list kept here) is left out of every answer, and
+ * so are its proposals. A placement of an initiative that has no record any more is left out with a flag.
+ *
+ * THE FOLD IS ORDER-FREE, like lib/plan-items.js: byte-identical duplicate lines (a union merge leaves them) count
+ * once, lines apply in (at, eid) order, and one eid with two contents keeps the first and flags the second. A later
+ * PM `placed` line for an initiative closes that initiative's open proposals (they are superseded, not adopted).
+ *
+ * HONEST LIMIT. The fold tells an agent's line by its `by`. An agent `placed` line without `proposed` is a line the
+ * writer never writes: the fold reads it as a proposal and flags it (`agent-not-proposed`); an `adopted` line by an
+ * agent is ignored and flagged. A forged `pm:` line is caught only by scripts/check-pm-lines.js (2B), not here.
+ *
+ * The ledger is one per repository: lib/plan-ledgers.js ledgerPath(root, 'placements'). Nothing is cached (D33).
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const ledgers = require('./plan-ledgers.js');
+const planTree = require('./plan-tree.js');
+const actorLib = require('./actor.js');
+const { createSinkGuard } = require('./sink.js');
+
+const HORIZONS = Object.freeze(['now', 'next', 'later']);
+const EVENTS = Object.freeze(['placed', 'created', 'adopted', 'dropped']);
+const MAX_LINES = 50;
+const DAY = 86400000;
+const INIT_RE = planTree.INIT_RE;
+const EID_RE = /^[0-9a-z]{12}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+const CAPTURE_RE = /^capture-\d{4}-\d{2}-\d{2}-[1-9]\d{0,3}$/;
+/** Fields only the writer sets. `proposed` too: the writer decides it from the actor. */
+const WRITER_SET = Object.freeze(['v', 'eid', 'by', 'via', 'at', 'override', 'pm', 'actor', 'nonce', 'proposed']);
+/** What a caller may send, per event (besides `ev`). */
+const CALLER_KEYS = Object.freeze({
+  placed: ['initiative', 'horizon', 'after', 'check_by'],
+  created: ['initiative', 'from'],
+  adopted: ['proposal'],
+  dropped: ['proposal'],
+});
+const ENVELOPE = ['v', 'eid', 'ev', 'by', 'via', 'at'];
+const STORED_KEYS = Object.freeze({
+  placed: [...ENVELOPE, ...CALLER_KEYS.placed, 'proposed'],
+  created: [...ENVELOPE, ...CALLER_KEYS.created],
+  adopted: [...ENVELOPE, ...CALLER_KEYS.adopted],
+  dropped: [...ENVELOPE, ...CALLER_KEYS.dropped],
+});
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+
+const isStr = (v) => typeof v === 'string';
+const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+const isPmBy = (by) => isStr(by) && by.startsWith('pm:');
+const dateOk = (v) => isStr(v) && DATE_RE.test(v) && !Number.isNaN(Date.parse(v + 'T00:00:00Z'))
+  && new Date(v + 'T00:00:00Z').toISOString().slice(0, 10) === v;
+
+function newEventId() {
+  let out = '';
+  while (out.length < 12) {
+    for (const b of crypto.randomBytes(24)) {
+      if (b >= 252) continue;                    // 252 = 7 × 36: keep the modulo unbiased
+      out += ALPHABET[b % 36];
+      if (out.length === 12) break;
+    }
+  }
+  return out;
+}
+
+// ── the stored line ─────────────────────────────────────────────────────────────────────────────────
+/** Why a stored line is not a valid line of this ledger, or null. */
+function lineErr(r) {
+  if (r.v !== 1) return 'v must be 1';
+  if (!isStr(r.eid) || !EID_RE.test(r.eid)) return 'eid must be 12 characters of [0-9a-z]';
+  if (!EVENTS.includes(r.ev)) return `ev must be one of ${EVENTS.join(', ')}`;
+  if (!isStr(r.by) || !actorLib.BY_RE.test(r.by)) return 'by must be pm:<slug>, agent:unknown or agent:<session>';
+  if (!actorLib.VIA.includes(r.via)) return 'via must be ui or cli';
+  if (!isStr(r.at) || !AT_RE.test(r.at)) return 'at must be an ISO UTC time';
+  const extra = Object.keys(r).filter((k) => !STORED_KEYS[r.ev].includes(k));
+  if (extra.length) return `a ${r.ev} line has no field ${extra.join(', ')}`;
+  if (r.ev === 'placed' || r.ev === 'created') {
+    if (!isStr(r.initiative) || !INIT_RE.test(r.initiative)) return 'initiative must be a record name';
+  }
+  if (r.ev === 'placed') {
+    if (!HORIZONS.includes(r.horizon)) return 'horizon must be now, next or later';
+    if (r.after !== null && !(isStr(r.after) && INIT_RE.test(r.after))) return 'after must be an initiative id or null';
+    if (r.after === r.initiative) return 'an initiative cannot come after itself';
+    if (has(r, 'check_by') && r.check_by !== null && !dateOk(r.check_by)) return 'check_by must be YYYY-MM-DD or null';
+    if (has(r, 'proposed') && r.proposed !== true) return 'proposed is true or absent';
+  }
+  if (r.ev === 'created' && has(r, 'from') && !(isStr(r.from) && CAPTURE_RE.test(r.from))) return 'from must name a capture note';
+  if ((r.ev === 'adopted' || r.ev === 'dropped') && !(isStr(r.proposal) && EID_RE.test(r.proposal))) return 'proposal must be the eid of a proposal';
+  return null;
+}
+
+// ── the fold ────────────────────────────────────────────────────────────────────────────────────────
+function emptyResult() {
+  return { ok: true, byInit: {}, order: { now: [], next: [], later: [] }, proposals: [], moves: [], flags: [] };
+}
+
+/** Sort, de-duplicate and validate the raw lines: [{ rec }] in (at, eid) order. Flags go into `out.flags`. */
+function orderLines(lines, out) {
+  const seen = new Map();   // eid -> canonical JSON
+  const kept = [];
+  for (const { n, rec } of lines) {
+    const why = lineErr(rec);
+    if (why) { out.flags.push({ kind: 'invalid', eid: isStr(rec.eid) ? rec.eid : null, init: isStr(rec.initiative) ? rec.initiative : null, why: `line ${n}: ${why}` }); continue; }
+    kept.push({ n, rec });
+  }
+  kept.sort((a, b) => (Date.parse(a.rec.at) - Date.parse(b.rec.at)) || (a.rec.eid < b.rec.eid ? -1 : a.rec.eid > b.rec.eid ? 1 : 0) || (a.n - b.n));
+  const outLines = [];
+  for (const l of kept) {
+    const text = JSON.stringify(l.rec);
+    if (seen.has(l.rec.eid)) {
+      if (seen.get(l.rec.eid) !== text) out.flags.push({ kind: 'duplicate-event', eid: l.rec.eid, init: l.rec.initiative || null, why: `line ${l.n}: the eid ${l.rec.eid} is used by two different lines; the first one counts` });
+      continue;   // byte-identical duplicates (a union merge) count once
+    }
+    seen.set(l.rec.eid, text);
+    outLines.push(l);
+  }
+  return outLines;
+}
+
+function place(out, id, horizon, after, checkBy, { confirmed, source, rec }) {
+  // A row seeded only as an anchor (it has a ledger line of its own, below) was never placed: its first line is its
+  // first placement, as when it was not seeded.
+  const prev = out.byInit[id] && !out.byInit[id].anchorOnly ? out.byInit[id] : null;
+  for (const h of HORIZONS) out.order[h] = out.order[h].filter((x) => x !== id);
+  const list = out.order[horizon];
+  const k = after ? list.indexOf(after) : -1;
+  if (!after) list.unshift(id); else if (k === -1) list.push(id); else list.splice(k + 1, 0, id);
+  out.byInit[id] = {
+    horizon, rank: 0, after: after || null,
+    check_by: checkBy === undefined ? (prev ? prev.check_by : null) : checkBy,
+    confirmed, dormant: false, source,
+  };
+  if (rec && (!prev || prev.horizon !== horizon)) out.moves.push({ init: id, from: prev ? prev.horizon : null, to: horizon, at: rec.at, by: rec.by, via: rec.via });
+}
+
+/** Every line applied in order. `open` is the map of open proposals by eid (the writer reads it). `seed` is day one's
+ *  rows ({ now: [id…], later: [id…] }, initiatives with no ledger line), placed BEFORE the lines apply, so a line whose
+ *  `after` names a day-one row finds it in the horizon. Without `seed` it is the ledger alone. */
+function foldLines(lines, seed) {
+  const out = emptyResult();
+  if (seed) {
+    for (const h of HORIZONS) {
+      for (const id of seed[h] || []) {
+        out.order[h].push(id);
+        out.byInit[id] = { horizon: h, rank: 0, after: null, check_by: null, confirmed: false, dormant: false, source: 'day-one' };
+        if (seed.anchorOnly && seed.anchorOnly.has(id)) out.byInit[id].anchorOnly = true;
+      }
+    }
+  }
+  const open = new Map();
+  const touched = new Set();
+  const created = new Map();   // initiative -> capture id it came from (or null)
+  for (const { n, rec } of orderLines(lines, out)) {
+    if (rec.ev === 'placed') {
+      const agentLine = !isPmBy(rec.by);
+      if (rec.proposed === true || agentLine) {
+        if (agentLine && rec.proposed !== true) out.flags.push({ kind: 'agent-not-proposed', eid: rec.eid, init: rec.initiative, why: `line ${n}: an agent's placement is a proposal; this one moved nothing` });
+        open.set(rec.eid, { eid: rec.eid, init: rec.initiative, horizon: rec.horizon, after: rec.after || null, check_by: has(rec, 'check_by') ? rec.check_by : undefined, by: rec.by, at: rec.at });
+        continue;
+      }
+      for (const [eid, p] of open) if (p.init === rec.initiative) open.delete(eid);   // superseded by the PM's own line
+      place(out, rec.initiative, rec.horizon, rec.after, has(rec, 'check_by') ? rec.check_by : undefined, { confirmed: true, source: 'ledger', rec });
+      touched.add(rec.initiative);
+    } else if (rec.ev === 'created') {
+      if (touched.has(rec.initiative)) { out.flags.push({ kind: 'created-twice', eid: rec.eid, init: rec.initiative, why: `line ${n}: ${rec.initiative} already had a placement; this landing line moved nothing` }); continue; }
+      place(out, rec.initiative, 'later', null, undefined, { confirmed: isPmBy(rec.by), source: 'created', rec });
+      touched.add(rec.initiative);
+      created.set(rec.initiative, rec.from || null);
+    } else {
+      const p = open.get(rec.proposal);
+      if (!p) { out.flags.push({ kind: 'unknown-proposal', eid: rec.eid, init: null, why: `line ${n}: ${rec.ev} names ${rec.proposal}, which is not an open proposal` }); continue; }
+      if (rec.ev === 'adopted') {
+        if (!isPmBy(rec.by)) { out.flags.push({ kind: 'adopt-not-pm', eid: rec.eid, init: p.init, why: `line ${n}: only the PM adopts a proposal; this line moved nothing` }); continue; }
+        open.delete(rec.proposal);
+        for (const [eid, q] of open) if (q.init === p.init) open.delete(eid);
+        place(out, p.init, p.horizon, p.after, p.check_by, { confirmed: true, source: 'ledger', rec });
+        touched.add(p.init);
+      } else {
+        if (!isPmBy(rec.by) && rec.by !== p.by) { out.flags.push({ kind: 'drop-not-allowed', eid: rec.eid, init: p.init, why: `line ${n}: only the PM or the agent that proposed it drops a proposal` }); continue; }
+        open.delete(rec.proposal);
+      }
+    }
+  }
+  return { out, open, created };
+}
+
+const activityMs = (r) => {
+  const v = r && r.last_activity;
+  if (typeof v === 'number' && Number.isFinite(v)) return v < 1e11 ? v * 1000 : v;   // the engine answers epoch seconds
+  const t = Date.parse(String(v || ''));
+  return Number.isFinite(t) ? t : null;
+};
+const finished = (r) => !!(r && (r.accepted || r.stopped));
+
+/** The `work` group of each lane, from the engine (lane-defs.js), unless every record already carries `group`. */
+function groupsOf(root, records) {
+  if (records.every((r) => isStr(r.group))) return null;
+  try {
+    const loaded = require('./console-state').loadEngine();
+    if (!loaded.ok) return {};
+    const { defs } = loaded.engine.lanesFor(root);
+    const out = {};
+    for (const [lane, d] of Object.entries(defs || {})) out[lane] = d && d.group;
+    return out;
+  } catch { return {}; }
+}
+
+function readPlacements(root, { now, rules, records } = {}) {
+  const { lines, bad } = ledgers.readLines(root, 'placements');
+  const ledgerOnly = foldLines(lines);
+
+  if (!Array.isArray(records)) {
+    const { out, open } = ledgerOnly;
+    for (const b of bad) out.flags.unshift({ kind: 'unreadable', eid: null, init: null, why: `line ${b.n}: ${b.why}` });
+    out.proposals = [...open.values()].map((p) => ({ eid: p.eid, init: p.init, horizon: p.horizon, after: p.after, by: p.by, at: p.at }));
+    for (const h of HORIZONS) out.order[h].forEach((id, i) => { out.byInit[id].rank = i; });
+    return out;
+  }
+
+  // ── day one and the work-lane filter (R26, D86 point 4) ──
+  const t = Number.isFinite(now) ? now : Date.now();
+  const stallMs = ((rules && rules.stall_days) || 5) * DAY;
+  const dormantMs = ((rules && rules.dormant_days) || 45) * DAY;
+  const groups = groupsOf(root, records);
+  const groupOf = (r) => (isStr(r.group) ? r.group : (groups && groups[r.lane]) || null);
+  const rows = new Map();
+  for (const r of records) if (r && isStr(r.id) && r.ok !== false) rows.set(r.id, r);
+  const isWork = (id) => rows.has(id) && groupOf(rows.get(id)) === 'work';
+
+  // Day one's rows: a work initiative with no line the ledger applied, placed by its activity. They are seeded into
+  // their horizon before the ledger lines apply, so a line placed `after` a day-one row (the page and the CLI send the
+  // displayed order) lands next to it. A ledger line with `after: null` still goes above them.
+  const byActivity = (a, b) => ((activityMs(rows.get(b)) || 0) - (activityMs(rows.get(a)) || 0)) || (a < b ? -1 : 1);
+  // A row that has a line of its own is seeded too, as an ANCHOR only: a line written while it was still a day-one row
+  // named it as `after`, and that line must find it where it stood then. Its own line moves it when it applies. Seeding
+  // only the rows with no line lost that anchor the moment the row got a line (the earlier line then appended its row
+  // at the end of the horizon), so one reorder could scramble rows it never touched.
+  const seed = { now: [], next: [], later: [], anchorOnly: new Set() };
+  for (const id of [...rows.keys()].filter((x) => isWork(x)).sort(byActivity)) {
+    const r = rows.get(id);
+    const ms = activityMs(r);
+    seed[!finished(r) && ms !== null && t - ms < stallMs ? 'now' : 'later'].push(id);
+    if (ledgerOnly.out.byInit[id]) seed.anchorOnly.add(id);
+  }
+  const { out, open } = foldLines(lines, seed);
+  for (const id of Object.keys(out.byInit)) if (out.byInit[id].anchorOnly) delete out.byInit[id].anchorOnly;
+  for (const b of bad) out.flags.unshift({ kind: 'unreadable', eid: null, init: null, why: `line ${b.n}: ${b.why}` });
+  const proposalsOf = (keep) => [...open.values()].filter((p) => keep(p.init))
+    .map((p) => ({ eid: p.eid, init: p.init, horizon: p.horizon, after: p.after, by: p.by, at: p.at }));
+
+  for (const id of Object.keys(out.byInit)) {
+    if (isWork(id)) continue;
+    if (!rows.has(id)) out.flags.push({ kind: 'no-record', eid: null, init: id, why: `${id} has a placement but no initiative record; it is left out` });
+    delete out.byInit[id];
+    for (const h of HORIZONS) out.order[h] = out.order[h].filter((x) => x !== id);
+  }
+  out.moves = out.moves.filter((m) => isWork(m.init));
+  out.proposals = proposalsOf(isWork);
+
+  // A finished initiative leaves Now by itself (R3): to the end of Later, whatever the ledger says.
+  for (const id of out.order.now.slice()) {
+    if (!finished(rows.get(id))) continue;
+    out.order.now = out.order.now.filter((x) => x !== id);
+    out.order.later.push(id);
+    out.byInit[id].horizon = 'later';
+  }
+  // Finished initiatives sit at the end of Later, in the order they were in.
+  out.order.later = [...out.order.later.filter((id) => !finished(rows.get(id))), ...out.order.later.filter((id) => finished(rows.get(id)))];
+  for (const id of out.order.later) {
+    const ms = activityMs(rows.get(id));
+    out.byInit[id].dormant = ms !== null && t - ms >= dormantMs;
+  }
+  for (const h of HORIZONS) out.order[h].forEach((id, i) => { out.byInit[id].rank = i; });
+  return out;
+}
+
+function pmOnly(rec) {
+  if (!rec) return false;
+  if (rec.ev === 'adopted') return true;
+  return rec.ev === 'placed' && rec.horizon === 'now' && rec.proposed !== true;
+}
+
+function horizonOf(result, id) {
+  const p = result && result.byInit && Object.prototype.hasOwnProperty.call(result.byInit, id) ? result.byInit[id] : null;
+  return p && HORIZONS.includes(p.horizon) ? p.horizon : 'later';
+}
+
+/** The capture notes an initiative was created from: { [captureId]: initiativeId } (lib/triage.js reads it). */
+function createdFrom(root) {
+  const { lines } = ledgers.readLines(root, 'placements');
+  const { created } = foldLines(lines);
+  const outMap = {};
+  for (const [id, from] of created) if (from) outMap[from] = id;
+  return outMap;
+}
+
+// ── the writer ──────────────────────────────────────────────────────────────────────────────────────
+const refuse = (status, error, index) => ({ ok: false, status, error, index: index == null ? null : index });
+
+/** One caller event → the stored line (without the envelope), or a refusal. `state` is the fold so far. */
+function buildRecord(root, ev, i, actor, state) {
+  if (!ev || typeof ev !== 'object' || Array.isArray(ev)) return refuse(400, 'each line must be a JSON object', i);
+  const sent = WRITER_SET.find((k) => has(ev, k));
+  if (sent) return refuse(400, `the writer sets "${sent}"; do not send it`, i);
+  if (!has(CALLER_KEYS, ev.ev)) return refuse(400, `ev must be one of ${EVENTS.join(', ')}`, i);
+  const extra = Object.keys(ev).filter((k) => k !== 'ev' && !CALLER_KEYS[ev.ev].includes(k));
+  if (extra.length) return refuse(400, `a ${ev.ev} line has no field ${extra.join(', ')}`, i);
+  const agent = !actorLib.isPm(actor);
+  const rec = { ev: ev.ev };
+  if (ev.ev === 'placed' || ev.ev === 'created') {
+    if (!isStr(ev.initiative) || !INIT_RE.test(ev.initiative)) return refuse(400, 'initiative must be an initiative id', i);
+    if (!planTree.recordPath(root, ev.initiative)) return refuse(404, `no initiative ${ev.initiative} in this repository`, i);
+    rec.initiative = ev.initiative;
+  }
+  if (ev.ev === 'placed') {
+    if (!HORIZONS.includes(ev.horizon)) return refuse(400, 'horizon must be now, next or later', i);
+    const after = ev.after == null ? null : ev.after;
+    if (after !== null && !(isStr(after) && INIT_RE.test(after))) return refuse(400, 'after must be an initiative id or null', i);
+    if (after === ev.initiative) return refuse(400, 'an initiative cannot come after itself', i);
+    rec.horizon = ev.horizon;
+    rec.after = after;
+    if (has(ev, 'check_by')) {
+      if (ev.check_by !== null && !dateOk(ev.check_by)) return refuse(400, 'check_by must be YYYY-MM-DD, or null to clear it', i);
+      rec.check_by = ev.check_by;
+    }
+    if (agent) rec.proposed = true;   // an agent's placement is a proposal, whatever it names (R23)
+  } else if (ev.ev === 'created') {
+    if (has(ev, 'from')) {
+      if (!(isStr(ev.from) && CAPTURE_RE.test(ev.from))) return refuse(400, 'from must name a capture note, like capture-2026-10-04-1', i);
+      rec.from = ev.from;
+    }
+    if (state.out.byInit[ev.initiative] || state.created.has(ev.initiative)) return refuse(409, `${ev.initiative} already has a place on the Roadmap`, i);
+  } else {
+    if (!isStr(ev.proposal) || !EID_RE.test(ev.proposal)) return refuse(400, 'proposal must be the eid of a proposal', i);
+    const p = state.open.get(ev.proposal);
+    if (!p) return refuse(404, `${ev.proposal} is not an open proposal`, i);
+    if (ev.ev === 'adopted' && agent) return refuse(403, 'only the PM adopts a proposal', i);
+    if (ev.ev === 'dropped' && agent && actor.by !== p.by) return refuse(403, 'an agent drops only its own proposal', i);
+    rec.proposal = ev.proposal;
+  }
+  return { ok: true, rec };
+}
+
+function append(root, events, actor, { now } = {}) {
+  if (!actorLib.valid(actor)) return refuse(500, 'placements: the caller must pass the actor from pm-guard.js or actor.js', null);
+  if (!Array.isArray(events) || !events.length) return refuse(400, 'send at least one line', null);
+  if (events.length > MAX_LINES) return refuse(413, `send at most ${MAX_LINES} lines at once`, null);
+  const read = ledgers.readLines(root, 'placements');
+  if (read.bad.some((b) => b.n === 0)) return refuse(500, 'could not read the placements ledger — nothing was saved: ' + read.bad[0].why.slice(0, 160), null);
+  const lines = read.lines.slice();
+  // Strictly increasing `at`, as plan-items.js: a line dated more than a second ahead is ignored for the floor.
+  const clock = now == null ? Date.now() : now;
+  let last = 0;
+  for (const l of lines) {
+    const t = isStr(l.rec.at) ? Date.parse(l.rec.at) : NaN;
+    if (Number.isFinite(t) && t <= clock + 1000 && t > last) last = t;
+  }
+  const recs = [];
+  for (let i = 0; i < events.length; i++) {
+    const state = foldLines(lines);
+    const r = buildRecord(root, events[i], i, actor, state);
+    if (!r.ok) return r;
+    last = Math.max(clock, last + 1);
+    const rec = { v: 1, eid: newEventId(), ...r.rec, by: actor.by, via: actor.via, at: new Date(last).toISOString() };
+    recs.push(rec);
+    lines.push({ n: lines.length + 1, rec });
+  }
+  let file;
+  try { file = ledgers.ledgerPath(root, 'placements'); fs.mkdirSync(path.dirname(file), { recursive: true }); }
+  catch { return refuse(500, 'could not record — nothing was saved', null); }
+  const guard = createSinkGuard({ sink: file, what: 'placements' });
+  let wrote = 0;
+  for (const rec of recs) {
+    try { guard.appendLine(file, rec); wrote++; }
+    catch {
+      return refuse(500, wrote ? `could not record — ${wrote} of ${recs.length} lines were saved before the write failed` : 'could not record — nothing was saved', wrote);
+    }
+  }
+  return { ok: true, written: recs.length, lines: recs.map((r) => ({ eid: r.eid, ev: r.ev, initiative: r.initiative || null, proposed: r.proposed === true })) };
+}
+
+/** A page press. The actor is the guard's (requirePmPress for Now and adopt, requirePagePress otherwise). */
+function appendFromUi(root, events, { actor, now } = {}) { return append(root, events, actor, { now }); }
+/** `pmos initiative`. The actor is requirePmCli's (Now, adopt) or actor.fromCli's. */
+function appendFromCli(root, events, { actor, now } = {}) { return append(root, events, actor, { now }); }
+
+module.exports = {
+  HORIZONS, EVENTS, MAX_LINES, CAPTURE_RE,
+  readPlacements, horizonOf, pmOnly, createdFrom, lineErr, appendFromUi, appendFromCli,
+};