@elvisw/dsh-magic-context 0.0.0-stage → 0.14.0

package/lib/core/directive-detect.js

@@ -0,0 +1,147 @@
+/**
+ * Directive-shape detection for profile candidates.
+ *
+ * Why this exists
+ * ---------------
+ * A user-profile entry that *describes* the person is safe to maintain
+ * automatically. An entry that *instructs the agent* is not: it is injected into
+ * every session on the machine, and a hallucinated behavioural rule ("accepts
+ * commits without tests") changes what the agent does everywhere. Magic
+ * Context promoted both kinds automatically — its only gate was a pool-size
+ * count, and the "at least N semantically similar variants" requirement lived
+ * in the prompt with no code behind it. Of the 17 live profile rows two thirds
+ * turned out to be behavioural rules.
+ *
+ * So: directive-shaped content must be confirmed by a human before it can take
+ * effect. This module decides WHICH candidates have to ask.
+ *
+ * The error asymmetry is the whole design:
+ *   - a false POSITIVE costs one question (annoying, safe);
+ *   - a false NEGATIVE lets an unreviewed rule into every session (the failure
+ *     this exists to prevent).
+ * The rule set is therefore built to over-trigger, and the regression suite
+ * (tests/directive-detect.spec.ts) requires ZERO misses on the labelled corpus
+ * while merely BOUNDING the harmless direction.
+ *
+ * A second signal keeps the noise down: an obligation is only directive-shaped
+ * when it targets something an agent can DO. "Not accepting a downstream
+ * fallback for data problems" is an attitude (descriptive); "must discuss in
+ * plan mode before writing any file" is an instruction.
+ */
+/** An obligation must reach this weight before the shape is directive. */
+export const DIRECTIVE_SCORE_THRESHOLD = 2;
+/** Obligations strong enough to stand alone. */
+const HARD_RULES = [
+    { rule: 'obligation:必须', weight: 2, pattern: /必须/ },
+    { rule: 'obligation:务必', weight: 2, pattern: /务必/ },
+    { rule: 'prohibition:严禁', weight: 2, pattern: /严禁/ },
+    { rule: 'prohibition:禁止', weight: 2, pattern: /禁止/ },
+    { rule: 'prohibition:不得', weight: 2, pattern: /不得/ },
+    { rule: 'prohibition:不允许', weight: 2, pattern: /不允许/ },
+    { rule: 'prohibition:不可以', weight: 2, pattern: /不可以/ },
+    { rule: 'obligation:一律', weight: 2, pattern: /一律/ },
+    { rule: 'obligation:只能', weight: 2, pattern: /只能/ },
+    { rule: 'gate:未确认前不', weight: 2, pattern: /未[^。；]{0,12}前不/ },
+    { rule: 'gate:放行门禁', weight: 2, pattern: /放行门禁/ },
+    { rule: 'obligation:en-must', weight: 2, pattern: /\bmust\b/i },
+    { rule: 'prohibition:en-never', weight: 2, pattern: /\bnever\b/i },
+    { rule: 'obligation:en-always', weight: 2, pattern: /\balways\b/i },
+    { rule: 'prohibition:en-do-not', weight: 2, pattern: /\bdo not\b/i },
+    { rule: 'obligation:en-required-to', weight: 2, pattern: /\brequired to\b/i },
+    { rule: 'gate:en-before-doing', weight: 2, pattern: /\bbefore (writing|making|committing|pushing|deploying|changing|running)/i },
+];
+/**
+ * Requirements that carry weight only together or with an explicit gate. The
+ * `要求…先/再/才` shape is the most valuable one: it describes a process the
+ * agent must follow, which is exactly what a directive is.
+ */
+const SOFT_RULES = [
+    { rule: 'requirement:要求…先/再/才/不要', weight: 2, pattern: /要求[^。；]{0,20}(先|再|才|必须|不要|不得)/ },
+    { rule: 'refusal:拒绝…任何/用', weight: 2, pattern: /拒绝[^。；]{0,12}(任何|用)/ },
+    { rule: 'refusal:不接受…兜底/妥协/凑数', weight: 2, pattern: /不接受[^。；]{0,12}(兜底|妥协|凑数)/ },
+    { rule: 'insistence:坚持…以/把…作为/为准', weight: 1, pattern: /坚持[^。；]{0,12}(以|把)[^。；]{0,24}(作为|为准)/ },
+    { rule: 'process:强制', weight: 1, pattern: /强制/ },
+    { rule: 'process:严格执行', weight: 1, pattern: /严格执行/ },
+    { rule: 'process:严格顺序', weight: 1, pattern: /严格顺序/ },
+];
+/**
+ * Something an agent can do. An obligation that targets none of these is about
+ * the world (a standard, a preference, a data-quality stance), not an
+ * instruction to the agent.
+ */
+const ACTION_RULES = [
+    { rule: 'action:写文件/代码', weight: 0, pattern: /写(文件|代码)/ },
+    { rule: 'action:推送', weight: 0, pattern: /推送/ },
+    { rule: 'action:提交', weight: 0, pattern: /提交/ },
+    { rule: 'action:部署', weight: 0, pattern: /部署/ },
+    { rule: 'action:修复', weight: 0, pattern: /修复/ },
+    { rule: 'action:删除', weight: 0, pattern: /删除/ },
+    { rule: 'action:提醒/提示', weight: 0, pattern: /提醒|提示|通知/ },
+    { rule: 'action:报告/汇报', weight: 0, pattern: /报告|汇报/ },
+    { rule: 'action:运行/执行', weight: 0, pattern: /运行|执行/ },
+    { rule: 'action:测试/验证', weight: 0, pattern: /测试|验证/ },
+    { rule: 'action:落地/推进', weight: 0, pattern: /落地|推进/ },
+    { rule: 'action:确认/核对', weight: 0, pattern: /确认|核对|核实/ },
+    { rule: 'action:评估', weight: 0, pattern: /评估/ },
+    { rule: 'action:清理/删除', weight: 0, pattern: /清理/ },
+    { rule: 'action:保持/避免', weight: 0, pattern: /保持|避免/ },
+    { rule: 'action:遵循/遵守', weight: 0, pattern: /遵循|遵守/ },
+    { rule: 'action:备份/安装/配置', weight: 0, pattern: /备份|安装|配置/ },
+    { rule: 'action:切换/回退', weight: 0, pattern: /切换|回退|切回/ },
+    { rule: 'action:en-verb', weight: 0, pattern: /\b(run|push|commit|test|write|delete|deploy|verify|confirm|wait|backup|review|ensure|check|update|refactor)\b/i },
+];
+const ALL_RULES = [...HARD_RULES, ...SOFT_RULES, ...ACTION_RULES];
+function kindOf(rule) {
+    if (HARD_RULES.includes(rule))
+        return 'hard';
+    if (SOFT_RULES.includes(rule))
+        return 'soft';
+    return 'action';
+}
+/** Every rule that fires, in declaration order, with the matched text. */
+export function detectDirectiveHits(text) {
+    const hits = [];
+    for (const rule of ALL_RULES) {
+        const match = rule.pattern.exec(text);
+        if (match !== null) {
+            hits.push({ rule: rule.rule, kind: kindOf(rule), match: match[0] });
+        }
+    }
+    return hits;
+}
+/**
+ * Classify one profile candidate. Conservative by construction: the shape is
+ * `directive` when the obligation weight reaches the threshold AND at least one
+ * action cue is present.
+ */
+export function classifyProfileShape(text) {
+    const hits = detectDirectiveHits(text);
+    const weightOf = (rule) => ALL_RULES.find(candidate => candidate.rule === rule)?.weight ?? 0;
+    const score = hits.reduce((total, hit) => total + weightOf(hit.rule), 0);
+    const hasAction = hits.some(hit => hit.kind === 'action');
+    const shape = score >= DIRECTIVE_SCORE_THRESHOLD && hasAction ? 'directive' : 'descriptive';
+    return {
+        shape,
+        score,
+        hits,
+        reasons: hits.map(hit => hit.rule),
+    };
+}
+export function isDirectiveShaped(text) {
+    return classifyProfileShape(text).shape === 'directive';
+}
+/**
+ * The question a directive-shaped candidate has to answer before it may enter
+ * the profile. It states the blast radius, because that is what the human is
+ * actually deciding about.
+ */
+export function buildConfirmationQuestion(content, verdict) {
+    const why = verdict.hits.filter(hit => hit.kind !== 'action').map(hit => hit.rule).join(', ');
+    return [
+        '一条画像候选读起来像**行为指令**，而不是对使用者的描述。',
+        `候选内容：${content}`,
+        why === '' ? '' : `判定依据：${why}`,
+        '确认后它会在**所有会话**中生效（不分项目）。',
+        '请回复：确认 / 改为描述型 / 丢弃。',
+    ].filter(line => line !== '').join('\n');
+}

package/lib/core/domain-reconcile.js

@@ -0,0 +1,394 @@
+/**
+ * Domain-row reconciliation — "publishing is a copy, not a mirror".
+ *
+ * A human approval publishes a candidate into the shared contract store under a
+ * domain identity (`dir:global:org` / `dir:global:machine`), and that is where
+ * the lane stops: the published row is a COPY. When the source memory is later
+ * rewritten or archived, nothing propagates, and nothing notices. Measured on
+ * the live store (2026-10-16): 27 candidates, 21 linked to a domain row, 3 of
+ * those stale.
+ *
+ * This module is the missing audit plus the repair PLAN — never the repair's
+ * dangerous half:
+ *
+ *   - `source-rewritten` → stage a NEW pending candidate for that domain, so a
+ *     human can approve republishing the source's current text. Nothing is
+ *     published here, and the stale row is deliberately left standing.
+ *   - `source-archived` / `source-missing` → archive the domain row
+ *     (`status='archived'`, never a DELETE). A withdrawal is as much a human
+ *     decision as a publish, so it only ever happens behind an explicit
+ *     `--write`.
+ *
+ * The red line this file exists to keep: **the reconciler must never publish.**
+ * It therefore has no seam for it at all — {@link DomainRepairPort} carries
+ * exactly two writes (archive one row, stage one candidate) and `applyRepair`
+ * can do nothing else with them. `tests/domain-reconcile.spec.ts` proves the line
+ * by handing `applyRepair` a publish function that throws.
+ *
+ * Everything here is pure: plain arrays in, plain data out, no database, no
+ * filesystem, no printing. `scripts/domain-reconcile.mjs` owns the SQL, the
+ * backup gate and the Chinese report; the module is what can be tested.
+ */
+/**
+ * The contract's "still there" vocabulary. `permanent` is a live status (the
+ * promotion path can set it), so a predicate named `status !== 'active'` would
+ * read every permanent source as dead and propose withdrawing healthy rows.
+ * The corpus holds only `active`/`archived` today; the second value is here so
+ * the audit cannot misfire the day one appears.
+ */
+const ALIVE_STATUSES = new Set(['active', 'permanent']);
+function isAlive(status) {
+    return ALIVE_STATUSES.has(status);
+}
+const KEY_SEP = '\u0000';
+/** `(domain_id, normalized_hash)` as one map key. NUL cannot occur in either. */
+function linkKey(domainId, normalizedHash) {
+    return `${domainId}${KEY_SEP}${normalizedHash}`;
+}
+/**
+ * The one row a candidate is linked to.
+ *
+ * The contract allows the same hash twice under one domain when the categories
+ * differ (`UNIQUE(project_path, category, normalized_hash)`), so "the" row needs
+ * a rule: the one whose category matches the candidate's, else the lowest id.
+ * Deterministic on purpose — the audit must not depend on read order.
+ */
+function pickDomainRow(rows, category) {
+    if (rows === undefined || rows.length === 0)
+        return undefined;
+    const exact = rows.filter(row => row.category === category);
+    const pool = exact.length > 0 ? exact : rows;
+    return pool.reduce((lowest, row) => (row.id < lowest.id ? row : lowest), pool[0]);
+}
+/**
+ * Is the source's CURRENT text already handled under this domain?
+ *
+ * Three honest forms of coverage: an ALIVE domain row holding that text; a
+ * PENDING candidate proposing it (the design's own repair — a rewrite stages a
+ * proposal rather than republishing); or a REJECTED candidate for exactly that
+ * text, which is a recorded human decision rather than an outstanding task. A
+ * merely `approved` candidate proves nothing: approval is a state flag, and the
+ * point of this audit is that the copy it produced may since have been
+ * withdrawn (live case #1420, archived).
+ */
+function findCoverage(domainId, sourceNormalizedHash, rowsByKey, candidatesByKey) {
+    const key = linkKey(domainId, sourceNormalizedHash);
+    for (const row of rowsByKey.get(key) ?? []) {
+        if (isAlive(row.status))
+            return { via: 'published', coveredBy: row.id };
+    }
+    for (const candidate of candidatesByKey.get(key) ?? []) {
+        if (candidate.state === 'pending')
+            return { via: 'staged', coveredBy: candidate.id };
+    }
+    for (const candidate of candidatesByKey.get(key) ?? []) {
+        if (candidate.state === 'rejected')
+            return { via: 'declined', coveredBy: candidate.id };
+    }
+    return undefined;
+}
+function makeDivergence(kind, candidate, row, sourceMemoryId, source) {
+    return {
+        kind,
+        candidateId: candidate.id,
+        domainId: candidate.domainId,
+        domainRowId: row.id,
+        sourceMemoryId,
+        publishedNormalizedHash: candidate.normalizedHash,
+        sourceNormalizedHash: source?.normalizedHash ?? null,
+        sourceCategory: source?.category ?? null,
+        sourceIdentity: source?.projectPath ?? null,
+        sourceContent: source?.content ?? null,
+    };
+}
+/**
+ * Classify one candidate. Exhaustive by construction: `checked` always equals
+ * `healthy + unlinked + divergences.length` (the spec asserts it).
+ */
+function classifyCandidate(candidate, rowsByKey, sourcesById, candidatesByKey) {
+    const row = pickDomainRow(rowsByKey.get(linkKey(candidate.domainId, candidate.normalizedHash)), candidate.category);
+    if (row === undefined)
+        return { outcome: 'unlinked' };
+    // A domain row that is already withdrawn cannot disagree with anything: the
+    // reviewer is looking at a fact nobody can see any more (semantics 3). It
+    // still counts as a healthy LINK — the number is reported separately so it is
+    // never silently padded.
+    if (!isAlive(row.status)) {
+        return { outcome: 'skipped-archived-row', domainRowId: row.id };
+    }
+    // Only an approved candidate is the authority for a published row; a rejected
+    // or still-pending one has never published anything, so it cannot be stale.
+    if (candidate.state !== 'approved')
+        return { outcome: 'healthy' };
+    const sourceMemoryId = candidate.sourceMemoryId;
+    // Machine-detected candidate: the link itself is the whole comparison, and
+    // there is no source that could have moved on.
+    if (sourceMemoryId === null || sourceMemoryId === undefined)
+        return { outcome: 'healthy' };
+    const source = sourcesById.get(sourceMemoryId);
+    if (source === undefined) {
+        return { outcome: 'divergence', divergence: makeDivergence('source-missing', candidate, row, sourceMemoryId, undefined) };
+    }
+    if (!isAlive(source.status)) {
+        return { outcome: 'divergence', divergence: makeDivergence('source-archived', candidate, row, sourceMemoryId, source) };
+    }
+    if (source.normalizedHash !== candidate.normalizedHash) {
+        // The source moved on. Before calling that a divergence, ask whether its
+        // CURRENT text is already handled under this domain — otherwise a repaired
+        // domain could never settle (the stale pair keeps its old hash forever).
+        const coverage = findCoverage(candidate.domainId, source.normalizedHash, rowsByKey, candidatesByKey);
+        if (coverage !== undefined) {
+            return {
+                outcome: 'covered',
+                covered: {
+                    candidateId: candidate.id,
+                    domainRowId: row.id,
+                    sourceMemoryId,
+                    via: coverage.via,
+                    coveredBy: coverage.coveredBy,
+                },
+            };
+        }
+        return { outcome: 'divergence', divergence: makeDivergence('source-rewritten', candidate, row, sourceMemoryId, source) };
+    }
+    return { outcome: 'healthy' };
+}
+/**
+ * The read-only half: what disagrees with what.
+ *
+ * `checked` counts every candidate given, which is the whole queue — rejected
+ * and pending candidates land in `unlinked` because they were never published.
+ * That is not a fault (the live store's 6 unlinked candidates are exactly 5
+ * rejected + 1 pending), so every caller must print `unlinked` as a note, never
+ * as an alarm.
+ */
+export function auditDomainDivergences(input) {
+    const rowsByKey = new Map();
+    for (const row of input.domainRows) {
+        const key = linkKey(row.domainId, row.normalizedHash);
+        const bucket = rowsByKey.get(key);
+        if (bucket === undefined)
+            rowsByKey.set(key, [row]);
+        else
+            bucket.push(row);
+    }
+    const sourcesById = new Map();
+    for (const memory of input.sourceMemories)
+        sourcesById.set(memory.id, memory);
+    // Every candidate, by key: coverage can come from a DIFFERENT candidate than
+    // the one being classified (the proposal staged for this very rewrite).
+    const candidatesByKey = new Map();
+    for (const candidate of input.candidates) {
+        const key = linkKey(candidate.domainId, candidate.normalizedHash);
+        const bucket = candidatesByKey.get(key);
+        if (bucket === undefined)
+            candidatesByKey.set(key, [candidate]);
+        else
+            bucket.push(candidate);
+    }
+    let checked = 0;
+    let healthy = 0;
+    let unlinked = 0;
+    const unlinkedCandidateIds = [];
+    const skippedArchivedDomainRows = [];
+    const covered = [];
+    const divergences = [];
+    for (const candidate of input.candidates) {
+        checked += 1;
+        const verdict = classifyCandidate(candidate, rowsByKey, sourcesById, candidatesByKey);
+        if (verdict.outcome === 'unlinked') {
+            unlinked += 1;
+            unlinkedCandidateIds.push(candidate.id);
+        }
+        else if (verdict.outcome === 'healthy') {
+            healthy += 1;
+        }
+        else if (verdict.outcome === 'skipped-archived-row') {
+            healthy += 1;
+            skippedArchivedDomainRows.push({ candidateId: candidate.id, domainRowId: verdict.domainRowId });
+        }
+        else if (verdict.outcome === 'covered') {
+            // Nothing to repair, so nothing keeps it out of `healthy`; listed anyway.
+            healthy += 1;
+            covered.push(verdict.covered);
+        }
+        else {
+            divergences.push(verdict.divergence);
+        }
+    }
+    return {
+        checked,
+        healthy,
+        unlinked,
+        unlinkedCandidateIds,
+        skippedArchivedDomainRows,
+        covered: covered.slice().sort((left, right) => left.candidateId - right.candidateId),
+        divergences: divergences.slice().sort((left, right) => left.candidateId - right.candidateId),
+    };
+}
+/** `dir:global:machine` → 'machine'. Anything else → null (never guessed). */
+function suggestedDomainFor(domainId) {
+    if (domainId.endsWith(':machine'))
+        return 'machine';
+    if (domainId.endsWith(':org'))
+        return 'org';
+    return null;
+}
+/** The one-line "why" the review card shows for a staged proposal. */
+export function reconcileReason(divergence) {
+    return `domain-reconcile: the published copy under ${divergence.domainId} is stale — source memory `
+        + `#${String(divergence.sourceMemoryId)} was rewritten after domain row #${String(divergence.domainRowId)} `
+        + `was published from hash ${divergence.publishedNormalizedHash}; approving republishes the current text `
+        + '(the stale row is left in place for a human to withdraw).';
+}
+/**
+ * Turn a report into the exact writes a repair would perform. Pure, and still
+ * not applied: the CLI decides, and only `--write` gets there.
+ *
+ * Two rules are load-bearing:
+ *
+ *   1. **A rewrite never archives.** The stale row is a fact somebody approved;
+ *      the proposal adds a new one and leaves the old decision visible.
+ *   2. **One proposal per unique key.** The adapter's unique index is
+ *      `(domain_id, normalized_hash)`, so a second idempotent write of the same
+ *      proposal would upsert the first one's row — and that upsert rewrites
+ *      `content` even for an APPROVED candidate. Collapsing here (and again at
+ *      the write seam) is what makes a repeated `--write` a no-op.
+ */
+export function planRepair(report) {
+    const archiveRowIds = [];
+    const archiveSeen = new Set();
+    const stageCandidates = [];
+    const stageIndex = new Map();
+    const unrepairable = [];
+    const archive = (rowId) => {
+        if (archiveSeen.has(rowId))
+            return;
+        archiveSeen.add(rowId);
+        archiveRowIds.push(rowId);
+    };
+    for (const divergence of report.divergences) {
+        if (divergence.kind !== 'source-rewritten') {
+            archive(divergence.domainRowId);
+            continue;
+        }
+        const { sourceContent, sourceNormalizedHash, sourceCategory, sourceIdentity } = divergence;
+        if (sourceContent === null || sourceNormalizedHash === null || sourceCategory === null || sourceIdentity === null) {
+            unrepairable.push({
+                candidateId: divergence.candidateId,
+                domainId: divergence.domainId,
+                kind: divergence.kind,
+                reason: 'the audit classified this as a rewrite but carried no source text — refusing to guess a proposal',
+            });
+            continue;
+        }
+        const key = linkKey(divergence.domainId, sourceNormalizedHash);
+        const existing = stageIndex.get(key);
+        const derived = { candidateId: divergence.candidateId, domainRowId: divergence.domainRowId, sourceMemoryId: divergence.sourceMemoryId };
+        if (existing !== undefined) {
+            const kept = stageCandidates[existing];
+            stageCandidates[existing] = { ...kept, derivedFrom: [...kept.derivedFrom, derived] };
+            continue;
+        }
+        stageIndex.set(key, stageCandidates.length);
+        stageCandidates.push({
+            domainId: divergence.domainId,
+            content: sourceContent,
+            normalizedHash: sourceNormalizedHash,
+            category: sourceCategory,
+            sourceMemoryId: divergence.sourceMemoryId,
+            sourceIdentity,
+            suggestedDomain: suggestedDomainFor(divergence.domainId),
+            reason: reconcileReason(divergence),
+            derivedFrom: [derived],
+        });
+    }
+    archiveRowIds.sort((left, right) => left - right);
+    return { archiveRowIds, stageCandidates, unrepairable };
+}
+/**
+ * Apply a plan through the injected port. This is the only function that writes,
+ * and the only two things it can write are the two the port exposes.
+ *
+ * Withdrawals run first, then proposals: a refusal while staging must not leave
+ * a half-applied plan looking complete, and the two sets are disjoint by
+ * construction (one divergence is either a rewrite or a dead source, never
+ * both). Every action is reported individually — a partial run prints as a
+ * partial run.
+ */
+export function applyRepair(plan, port, options = {}) {
+    const at = options.now ?? Date.now();
+    const journal = options.journal;
+    const archived = [];
+    const archiveRefusals = [];
+    const staged = [];
+    const stageRefusals = [];
+    for (const rowId of plan.archiveRowIds) {
+        const result = port.archiveDomainRow(rowId);
+        if (result.ok) {
+            if (result.changed)
+                archived.push(rowId);
+            else
+                archiveRefusals.push({ rowId, error: 'already archived (idempotent re-run)' });
+            journal?.({
+                at,
+                action: result.changed ? 'archive' : 'refuse',
+                summary: result.changed
+                    ? `archived domain row #${String(rowId)} (its source memory is gone)`
+                    : `domain row #${String(rowId)} was already archived`,
+                data: { rowId, changed: result.changed },
+            });
+        }
+        else {
+            archiveRefusals.push({ rowId, error: result.error });
+            journal?.({ at, action: 'refuse', summary: `archive refused for domain row #${String(rowId)}`, data: { rowId, error: result.error } });
+        }
+    }
+    for (const proposal of plan.stageCandidates) {
+        const result = port.stageCandidate(proposal);
+        if (result.ok) {
+            const reproposed = result.reproposed === true;
+            staged.push({
+                domainId: proposal.domainId,
+                normalizedHash: proposal.normalizedHash,
+                sourceMemoryId: proposal.sourceMemoryId,
+                candidateId: result.candidateId,
+                created: result.created,
+                reproposed,
+            });
+            journal?.({
+                at,
+                action: 'stage',
+                summary: result.created
+                    ? `staged candidate #${String(result.candidateId)} for ${proposal.domainId} (awaiting human approval)`
+                    : reproposed
+                        ? `re-proposed dead candidate #${String(result.candidateId)} for ${proposal.domainId} (its published copy is archived; awaiting human approval again)`
+                        : `candidate #${String(result.candidateId)} already staged for ${proposal.domainId}`,
+                data: {
+                    candidateId: result.candidateId,
+                    domainId: proposal.domainId,
+                    normalizedHash: proposal.normalizedHash,
+                    sourceMemoryId: proposal.sourceMemoryId,
+                    derivedFrom: proposal.derivedFrom,
+                    created: result.created,
+                    reproposed,
+                },
+            });
+        }
+        else {
+            stageRefusals.push({
+                domainId: proposal.domainId,
+                normalizedHash: proposal.normalizedHash,
+                sourceMemoryId: proposal.sourceMemoryId,
+                error: result.error,
+            });
+            journal?.({
+                at,
+                action: 'refuse',
+                summary: `staging refused for ${proposal.domainId}`,
+                data: { domainId: proposal.domainId, normalizedHash: proposal.normalizedHash, error: result.error },
+            });
+        }
+    }
+    return { archived, archiveRefusals, staged, stageRefusals, unrepairable: plan.unrepairable };
+}

package/lib/core/domains.js

@@ -0,0 +1,127 @@
+/**
+ * The adapter's global domains: `user` (the person), `org` (organisation
+ * knowledge), `machine` (this machine's environment).
+ *
+ * Display naming (2026-10-25, docs/domain-naming-work-global-2026-10-25.md):
+ * the axis is AUDIENCE, not distribution — `machine` surfaces as 全局/global
+ * (every project on this machine), `org` as 工作/work (a hand-curated member
+ * set of work projects). The internal tokens below are storage keys and never
+ * rename.
+ *
+ * Why domains exist at all
+ * ------------------------
+ * A *global* memory is one that is not owned by any single project. Magic
+ * Context ships exactly one such lane — the user profile — because a profile
+ * "applies everywhere" and therefore needs no activation rule. Organisation
+ * knowledge does not have that property: the company database pointer must be
+ * invisible in an open-source project's session. So the domain axis answers
+ * exactly one question — **under what circumstances should this be visible?** —
+ * and deliberately does not answer "what is it about" (that is `category`).
+ *
+ * One domain = one activation rule + one budget + one cap derived from it.
+ * The kind set is closed at three on purpose: a new kind has to earn its place
+ * with an independent activation rule, audience and budget.
+ *
+ * See docs/dsh-plugin-platform-takeover-and-global-domains-2026-10-09.md.
+ */
+import { V2_MEMORY_CATEGORIES } from "./memory-categories.js";
+/** The closed set of global domains. */
+export const DOMAIN_KINDS = ['user', 'org', 'machine'];
+export function isDomainKind(value) {
+    return typeof value === 'string' && DOMAIN_KINDS.includes(value);
+}
+/**
+ * Per-domain *render* budget in tokens. These are the numbers the composed
+ * baseline must respect; they are not the same as the cap's source (below)
+ * because `user` renders across two blocks (m[0] profile + m[1] delta) while
+ * remaining a curated, small set.
+ */
+export const DEFAULT_DOMAIN_BUDGET_TOKENS = {
+    user: 5000,
+    org: 768,
+    machine: 512,
+};
+/**
+ * The curation target a domain's cap is derived from. It differs from the
+ * render budget for `user` on purpose: the profile renders under a 4000-token
+ * m[0] budget, but an unbounded set of behavioural notes is not a curated
+ * profile — the cap has to be a product decision expressed as a token target.
+ */
+export const DEFAULT_DOMAIN_CAP_BUDGET_TOKENS = {
+    user: 750,
+    org: 768,
+    machine: 500,
+};
+/** Estimated tokens for one rendered memory line (content + list overhead). */
+export const DOMAIN_TOKENS_PER_LINE = 20;
+/** Headroom kept below the cap budget, so a domain never sits exactly at its ceiling. */
+export const DOMAIN_CAP_SAFETY = 0.8;
+/**
+ * A domain's cap is DERIVED, never picked: it is the number of lines the cap
+ * budget can hold, with headroom. Non-finite and non-positive budgets collapse
+ * to the floor of one line rather than to zero (a domain that can hold nothing
+ * would silently reject every candidate).
+ */
+export function deriveDomainCap(capBudgetTokens) {
+    if (!Number.isFinite(capBudgetTokens) || capBudgetTokens <= 0)
+        return 1;
+    return Math.max(1, Math.floor((capBudgetTokens / DOMAIN_TOKENS_PER_LINE) * DOMAIN_CAP_SAFETY));
+}
+export function defaultDomainCap(kind) {
+    return deriveDomainCap(DEFAULT_DOMAIN_CAP_BUDGET_TOKENS[kind]);
+}
+/** The provider identity that owns a domain's rows in the shared store. */
+export function domainIdentity(kind) {
+    return `dir:global:${kind}`;
+}
+/** What a missing allowlist means (the contract's own column default). */
+export const DEFAULT_SHARE_CATEGORIES = ['CONSTRAINTS'];
+/**
+ * Parse a share allowlist with the contract's fail-closed convention
+ * (upstream `normalizeShareCategories`, workspaces.ts:69-97):
+ *
+ *   missing/null  -> the default allowlist
+ *   malformed, not an array, or ANY unknown category -> `[]`, share nothing
+ *
+ * The asymmetry is deliberate and load-bearing: a corrupt allowlist must not
+ * silently widen what becomes visible across projects.
+ */
+export function parseShareCategories(raw) {
+    if (raw === null || raw === undefined)
+        return [...DEFAULT_SHARE_CATEGORIES];
+    if (typeof raw !== 'string')
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const valid = new Set(V2_MEMORY_CATEGORIES);
+    const categories = [];
+    for (const item of parsed) {
+        if (typeof item !== 'string' || !valid.has(item))
+            return [];
+        if (!categories.includes(item))
+            categories.push(item);
+    }
+    return categories.sort((left, right) => left.localeCompare(right));
+}
+/**
+ * Serialize an allowlist for storage, rejecting unknown categories. This is
+ * also the publish-time pre-check: a category outside the allowlist would be
+ * written and then be invisible forever, which is a silent failure — so it is
+ * refused here instead.
+ */
+export function serializeShareCategories(categories) {
+    const valid = new Set(V2_MEMORY_CATEGORIES);
+    for (const category of categories) {
+        if (!valid.has(category)) {
+            throw new Error(`unknown share category '${category}' (allowed: ${V2_MEMORY_CATEGORIES.join(', ')})`);
+        }
+    }
+    return JSON.stringify([...new Set(categories)].sort((left, right) => left.localeCompare(right)));
+}