@aitne/daemon 0.1.0

package/dist/core/integration-main-backend.d.ts

@@ -0,0 +1,36 @@
+import type Database from "better-sqlite3";
+import { type BackendId, type IntegrationKey } from "@aitne/shared";
+export interface DelegationCompatReport {
+    key: IntegrationKey;
+    /** User's explicit delegated backend choice (preserved across main switches). */
+    delegatedBackend: BackendId;
+    /** True when the NEW main backend has a registry connector for this integration. */
+    compatibleWithNewMain: boolean;
+}
+/**
+ * §4.12.4 "Backend change while delegated" — read-only detection.
+ *
+ * When the main backend changes and a Google integration is currently
+ * delegated, report whether the new main has a registry connector for that
+ * integration. The caller (PUT /api/backends/main) passes the report array
+ * through in its response so the dashboard can surface the divergence.
+ *
+ * **Does NOT mutate state.** In particular:
+ *   - `delegatedBackend` is never auto-rewired. The user's explicit choice
+ *     stands; a "rewire on compat" heuristic would erase the choice the
+ *     moment a user sets main = Codex while they had `delegatedBackend =
+ *     claude`. That would be a silent policy change, not a safety fix.
+ *   - No owner DM. Dispatch-time `BackendRouter.refineFallbackForDelegation`
+ *     (Phase 4) + `missing_variants` skill-compile guard (Phase 3) already
+ *     catch the actual execution failure, and emit owner-visible errors
+ *     from `handleFallbackFailure`. Proactively DMing from here would be a
+ *     duplicate at best, a false-alarm at worst (incompat ≠ executing).
+ *   - No integrations.md rewrite, no probe cache invalidation, no audit row.
+ *     The cached probe is keyed on `(integration, backend)` pairs — main
+ *     backend changes don't stale those rows.
+ *
+ * Incompat cases are logged at `warn` so a mis-configured install shows up
+ * in the daemon log without burning an owner notification.
+ */
+export declare function checkDelegatedCompatForNewMain(db: Database.Database, newMainBackendId: BackendId): DelegationCompatReport[];
+//# sourceMappingURL=integration-main-backend.d.ts.map

package/dist/core/integration-main-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-main-backend.d.ts","sourceRoot":"","sources":["../../src/core/integration-main-backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,cAAc,EAEpB,MAAM,eAAe,CAAC;AAMvB,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,cAAc,CAAC;IACpB,iFAAiF;IACjF,gBAAgB,EAAE,SAAS,CAAC;IAC5B,oFAAoF;IACpF,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,gBAAgB,EAAE,SAAS,GAC1B,sBAAsB,EAAE,CAiC1B"}

package/dist/core/integration-main-backend.js

@@ -0,0 +1,59 @@
+import { INTEGRATION_KEYS, backendHasIntegrationConnector, } from "@aitne/shared";
+import { readIntegrations } from "../db/integrations-store.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("integration-main-backend");
+/**
+ * §4.12.4 "Backend change while delegated" — read-only detection.
+ *
+ * When the main backend changes and a Google integration is currently
+ * delegated, report whether the new main has a registry connector for that
+ * integration. The caller (PUT /api/backends/main) passes the report array
+ * through in its response so the dashboard can surface the divergence.
+ *
+ * **Does NOT mutate state.** In particular:
+ *   - `delegatedBackend` is never auto-rewired. The user's explicit choice
+ *     stands; a "rewire on compat" heuristic would erase the choice the
+ *     moment a user sets main = Codex while they had `delegatedBackend =
+ *     claude`. That would be a silent policy change, not a safety fix.
+ *   - No owner DM. Dispatch-time `BackendRouter.refineFallbackForDelegation`
+ *     (Phase 4) + `missing_variants` skill-compile guard (Phase 3) already
+ *     catch the actual execution failure, and emit owner-visible errors
+ *     from `handleFallbackFailure`. Proactively DMing from here would be a
+ *     duplicate at best, a false-alarm at worst (incompat ≠ executing).
+ *   - No integrations.md rewrite, no probe cache invalidation, no audit row.
+ *     The cached probe is keyed on `(integration, backend)` pairs — main
+ *     backend changes don't stale those rows.
+ *
+ * Incompat cases are logged at `warn` so a mis-configured install shows up
+ * in the daemon log without burning an owner notification.
+ */
+export function checkDelegatedCompatForNewMain(db, newMainBackendId) {
+    const integrations = readIntegrations(db);
+    const reports = [];
+    for (const key of INTEGRATION_KEYS) {
+        const state = integrations[key];
+        if (state.mode !== "delegated")
+            continue;
+        const compatible = backendHasIntegrationConnector(key, newMainBackendId);
+        // Forward-compat: every (integration, backend) pair currently has a
+        // connector, so this warn-branch is unreachable from the live registry.
+        /* c8 ignore next 10 */
+        if (!compatible) {
+            logger.warn({
+                key,
+                newMainBackendId,
+                delegatedBackend: state.delegatedBackend,
+            }, "Delegated integration incompatible with new main backend — preserving user's delegatedBackend; dispatch-time guards will surface execution failures");
+        }
+        reports.push({
+            key,
+            // Zod's superRefine on integrationStateSchema guarantees
+            // delegatedBackend is set whenever mode === "delegated", but the TS
+            // type is not narrowed — cast to surface the invariant.
+            delegatedBackend: state.delegatedBackend,
+            compatibleWithNewMain: compatible,
+        });
+    }
+    return reports;
+}
+//# sourceMappingURL=integration-main-backend.js.map

package/dist/core/integration-main-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-main-backend.js","sourceRoot":"","sources":["../../src/core/integration-main-backend.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gBAAgB,EAChB,8BAA8B,GAI/B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,MAAM,MAAM,GAAG,YAAY,CAAC,0BAA0B,CAAC,CAAC;AAUxD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,8BAA8B,CAC5C,EAAqB,EACrB,gBAA2B;IAE3B,MAAM,YAAY,GAAG,gBAAgB,CAAC,EAAE,CAAC,CAAC;IAC1C,MAAM,OAAO,GAA6B,EAAE,CAAC;IAE7C,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,MAAM,KAAK,GAAqB,YAAY,CAAC,GAAG,CAAC,CAAC;QAClD,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW;YAAE,SAAS;QAEzC,MAAM,UAAU,GAAG,8BAA8B,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;QACzE,oEAAoE;QACpE,wEAAwE;QACxE,uBAAuB;QACvB,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,CAAC,IAAI,CACT;gBACE,GAAG;gBACH,gBAAgB;gBAChB,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;aACzC,EACD,qJAAqJ,CACtJ,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,IAAI,CAAC;YACX,GAAG;YACH,yDAAyD;YACzD,oEAAoE;YACpE,wDAAwD;YACxD,gBAAgB,EAAE,KAAK,CAAC,gBAA6B;YACrD,qBAAqB,EAAE,UAAU;SAClC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/core/integration-probe.d.ts

@@ -0,0 +1,98 @@
+import { type BackendId, type IntegrationBackendConnector, type IntegrationKey } from "@aitne/shared";
+/**
+ * Integration delegation framework — connector probe evaluator (§4.12.2).
+ *
+ * Pure function over (live tool list, integration descriptor, target backend).
+ * Returns which capabilities are present, which required ones are missing,
+ * and a `present` boolean callers use to gate the §4.12.2 commit step.
+ *
+ * The evaluator does NOT launch agent subprocesses. The caller is expected
+ * to gather the live MCP tool name list via whatever channel suits — the
+ * agent SDK's tool-listing API, the §7 POC scripts, or a stub for unit
+ * tests. This split keeps the cost-bearing piece (subprocess) out of the
+ * boot path: §4.11 startup uses cached results from the
+ * `integration_probes` DB table; only the explicit
+ * `POST /api/integrations/:key/probe` endpoint and post-mode-change flips
+ * trigger a fresh subprocess.
+ */
+export interface ProbeInput {
+    /** Live MCP tool names visible to the agent — full namespaced strings. */
+    tools: readonly string[];
+    /** Integration whose connector we are probing. */
+    integration: IntegrationKey;
+    /** Backend whose connector to consult. */
+    backend: BackendId;
+    /** Optional ISO timestamp of the probe. Defaults to `new Date().toISOString()`. */
+    probedAt?: string;
+}
+export interface ProbeCapabilityResult {
+    /** Capability name from `requiredCapabilities ∪ optionalCapabilities`. */
+    capability: string;
+    /** True iff at least one tool listed under `capabilityTools[capability]` was found. */
+    present: boolean;
+    /** The matching tool names that satisfied the capability (for diagnostics). */
+    matchedTools: readonly string[];
+    /** True when the capability is in `requiredCapabilities`. */
+    required: boolean;
+}
+export interface ProbeResult {
+    integration: IntegrationKey;
+    backend: BackendId;
+    /**
+     * Full namespaced tool names this connector exposed at probe time. Useful
+     * for the dashboard to render "we found 21 tools" without re-deriving.
+     */
+    presentTools: readonly string[];
+    /** Per-capability presence map for `requiredCapabilities ∪ optionalCapabilities`. */
+    capabilities: readonly ProbeCapabilityResult[];
+    /** Names of required capabilities with no matching tool. */
+    missingRequired: readonly string[];
+    /**
+     * True iff every `requiredCapabilities` entry was satisfied. The §4.12.2
+     * commit gate fails when this is false.
+     */
+    present: boolean;
+    /** ISO-8601 timestamp the probe was taken. */
+    probedAt: string;
+}
+/**
+ * Look up the connector for `(integration, backend)`. Returns null when the
+ * descriptor doesn't list this backend — the caller surfaces "this backend
+ * isn't a connector option" rather than synthesizing an empty probe.
+ */
+export declare function getConnector(integration: IntegrationKey, backend: BackendId): IntegrationBackendConnector | null;
+/**
+ * Build a synthetic probe result for a user-managed connector
+ * integration (e.g. Outlook). The daemon ships no descriptor-side tool
+ * inventory for these — the user installs an MCP / connector on the
+ * agent backend they pick, and the daemon trusts that wiring. The
+ * result has no capability rows (so the §4.12.2 commit gate is
+ * satisfied trivially and the dashboard renders the user-managed
+ * branch instead of a feature matrix), but `presentTools` carries the
+ * live tool list when one was passed — useful for diagnostics ("we saw
+ * N tools on your backend"). Callers without a live tool list (cached
+ * synthesis, /health default) pass an empty array.
+ */
+export declare function makeUserManagedProbeResult(integration: IntegrationKey, backend: BackendId, tools: readonly string[], probedAt?: string): ProbeResult;
+/**
+ * Pure evaluation. Returns a {@link ProbeResult} that callers persist via
+ * `writeProbe` (when this is a live probe) or pass directly to the /health
+ * snapshot builder (when the caller has a fresh result in hand).
+ */
+export declare function evaluateProbe(input: ProbeInput): ProbeResult;
+/**
+ * Shrink a probe result to the `{cap: boolean}` shape the §4.11 health
+ * endpoint exposes. Optional capabilities, required capabilities, both flow
+ * through identically — the consumer (dashboard / setup wizard) decides
+ * how to render the gap.
+ */
+export declare function probeFeaturesMap(result: ProbeResult): Readonly<Record<string, boolean>>;
+/**
+ * Synthesize a "trust-the-POC" features map from the descriptor's
+ * `optionalCapabilities` when no probe row exists yet. Every listed
+ * capability defaults to `true` because the POC inventory IS the probe
+ * result for the shipped registry. Used by /health to degrade gracefully
+ * before the user has run a live probe.
+ */
+export declare function descriptorDefaultFeaturesMap(integration: IntegrationKey, backend: BackendId): Readonly<Record<string, boolean>> | null;
+//# sourceMappingURL=integration-probe.d.ts.map

package/dist/core/integration-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-probe.d.ts","sourceRoot":"","sources":["../../src/core/integration-probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,2BAA2B,EAEhC,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,kDAAkD;IAClD,WAAW,EAAE,cAAc,CAAC;IAC5B,0CAA0C;IAC1C,OAAO,EAAE,SAAS,CAAC;IACnB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,6DAA6D;IAC7D,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,cAAc,CAAC;IAC5B,OAAO,EAAE,SAAS,CAAC;IACnB;;;OAGG;IACH,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,qFAAqF;IACrF,YAAY,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC/C,4DAA4D;IAC5D,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,cAAc,EAC3B,OAAO,EAAE,SAAS,GACjB,2BAA2B,GAAG,IAAI,CAMpC;AAoBD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,cAAc,EAC3B,OAAO,EAAE,SAAS,EAClB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,QAAQ,CAAC,EAAE,MAAM,GAChB,WAAW,CAUb;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CA4E5D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,GAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAMnC;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,cAAc,EAC3B,OAAO,EAAE,SAAS,GACjB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAc1C"}

package/dist/core/integration-probe.js

@@ -0,0 +1,152 @@
+import { INTEGRATION_DESCRIPTORS, } from "@aitne/shared";
+/**
+ * Look up the connector for `(integration, backend)`. Returns null when the
+ * descriptor doesn't list this backend — the caller surfaces "this backend
+ * isn't a connector option" rather than synthesizing an empty probe.
+ */
+export function getConnector(integration, backend) {
+    const descriptor = INTEGRATION_DESCRIPTORS[integration];
+    // The `?? null` fallback is forward-compat: every (integration, backend)
+    // pair currently has a connector. See the matching note on `evaluateProbe`.
+    /* c8 ignore next */
+    return descriptor.backendConnectors[backend] ?? null;
+}
+/**
+ * Match a list of `capabilityTools` (relative names) against the live `tools`
+ * list. A capability is present when at least one of its relative tool names
+ * concatenates with `toolNamespace` to a name found in `tools`.
+ */
+function matchCapability(toolNamespace, toolNames, liveTools) {
+    const matched = [];
+    for (const tool of toolNames) {
+        const fullName = toolNamespace + tool;
+        if (liveTools.has(fullName))
+            matched.push(fullName);
+    }
+    return matched;
+}
+/**
+ * Build a synthetic probe result for a user-managed connector
+ * integration (e.g. Outlook). The daemon ships no descriptor-side tool
+ * inventory for these — the user installs an MCP / connector on the
+ * agent backend they pick, and the daemon trusts that wiring. The
+ * result has no capability rows (so the §4.12.2 commit gate is
+ * satisfied trivially and the dashboard renders the user-managed
+ * branch instead of a feature matrix), but `presentTools` carries the
+ * live tool list when one was passed — useful for diagnostics ("we saw
+ * N tools on your backend"). Callers without a live tool list (cached
+ * synthesis, /health default) pass an empty array.
+ */
+export function makeUserManagedProbeResult(integration, backend, tools, probedAt) {
+    return {
+        integration,
+        backend,
+        presentTools: [...tools],
+        capabilities: [],
+        missingRequired: [],
+        present: true,
+        probedAt: probedAt ?? new Date().toISOString(),
+    };
+}
+/**
+ * Pure evaluation. Returns a {@link ProbeResult} that callers persist via
+ * `writeProbe` (when this is a live probe) or pass directly to the /health
+ * snapshot builder (when the caller has a fresh result in hand).
+ */
+export function evaluateProbe(input) {
+    const descriptor = INTEGRATION_DESCRIPTORS[input.integration];
+    // User-managed connector integrations (e.g. Outlook) — see
+    // {@link makeUserManagedProbeResult}. Defense-in-depth: every caller
+    // that goes through the route handler is already routed via the
+    // helper, but evaluators reached from observers (e.g. the periodic
+    // DelegatedProbeObserver) land here and the synthetic shape is the
+    // right answer for them too.
+    if (descriptor.userManagedConnector) {
+        return makeUserManagedProbeResult(input.integration, input.backend, input.tools, input.probedAt);
+    }
+    const connector = getConnector(input.integration, input.backend);
+    // Forward-compat: today every (integrationKey, BackendId) pair has a
+    // connector descriptor, so this branch is unreachable through the live
+    // registry. Reserved for a future integration that lands without all
+    // three backends. Surfaced via thrown so callers don't silently mask a
+    // misconfigured integration.
+    /* c8 ignore next 5 */
+    if (!connector) {
+        throw new Error(`No connector for ${input.integration} on backend ${input.backend}`);
+    }
+    const probedAt = input.probedAt ?? new Date().toISOString();
+    // Restrict the live tool list to ones in this connector's namespace so
+    // the evaluator's `presentTools` field doesn't drag in unrelated tools.
+    const namespacedTools = input.tools.filter((t) => t.startsWith(connector.toolNamespace));
+    const liveSet = new Set(namespacedTools);
+    // Union required + optional, dedup. Required entries keep their `required`
+    // flag so consumers can render the feature matrix without re-checking.
+    const requiredSet = new Set(connector.requiredCapabilities);
+    const allCapabilities = new Set([
+        ...connector.requiredCapabilities,
+        ...connector.optionalCapabilities,
+    ]);
+    const capabilities = [];
+    for (const capability of allCapabilities) {
+        // Connectors must list every required+optional capability in
+        // capabilityTools — see the registry self-consistency test in
+        // integration-probe.test.ts. A missing entry is a registry bug.
+        const tools = connector.capabilityTools[capability];
+        const matched = matchCapability(connector.toolNamespace, tools, liveSet);
+        capabilities.push({
+            capability,
+            present: matched.length > 0,
+            matchedTools: matched,
+            required: requiredSet.has(capability),
+        });
+    }
+    const missingRequired = capabilities
+        .filter((c) => c.required && !c.present)
+        .map((c) => c.capability);
+    return {
+        integration: input.integration,
+        backend: input.backend,
+        presentTools: namespacedTools,
+        capabilities,
+        missingRequired,
+        present: missingRequired.length === 0,
+        probedAt,
+    };
+}
+/**
+ * Shrink a probe result to the `{cap: boolean}` shape the §4.11 health
+ * endpoint exposes. Optional capabilities, required capabilities, both flow
+ * through identically — the consumer (dashboard / setup wizard) decides
+ * how to render the gap.
+ */
+export function probeFeaturesMap(result) {
+    const out = {};
+    for (const cap of result.capabilities) {
+        out[cap.capability] = cap.present;
+    }
+    return out;
+}
+/**
+ * Synthesize a "trust-the-POC" features map from the descriptor's
+ * `optionalCapabilities` when no probe row exists yet. Every listed
+ * capability defaults to `true` because the POC inventory IS the probe
+ * result for the shipped registry. Used by /health to degrade gracefully
+ * before the user has run a live probe.
+ */
+export function descriptorDefaultFeaturesMap(integration, backend) {
+    const connector = getConnector(integration, backend);
+    // Forward-compat: same case as `evaluateProbe`'s null guard — every
+    // (integration, backend) pair currently has a connector.
+    /* c8 ignore next */
+    if (!connector)
+        return null;
+    const out = {};
+    for (const cap of connector.optionalCapabilities) {
+        out[cap] = true;
+    }
+    for (const cap of connector.requiredCapabilities) {
+        out[cap] = true;
+    }
+    return out;
+}
+//# sourceMappingURL=integration-probe.js.map

package/dist/core/integration-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-probe.js","sourceRoot":"","sources":["../../src/core/integration-probe.ts"],"names":[],"mappings":"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"}

package/dist/core/management-md-write-lock.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `rules/management.md` write-lock manager — docs/design/21-management-
+ * registry-and-entities.md §11.1.
+ *
+ * Mirrors the {@link InMemoryTodayWriteLockManager} pattern (see
+ * `today-write-lock.ts`): a single in-process holder, an auto-release
+ * timer, and a UUID lock-id that callers MUST present back to release.
+ *
+ * The registry's render+write path acquires the lock for the duration
+ * of (render → atomic write → snapshot) so a competing API write or
+ * boot reconciler cannot interleave between the steps. A single-vault,
+ * single-daemon deployment makes an in-memory lock sufficient — the
+ * file is not edited from a sibling process. If multi-daemon access is
+ * ever introduced, swap the implementation for a `flock(2)`-backed one
+ * matching `migration-lock` semantics.
+ *
+ * Default timeout: 5 s, matching the design's call-out and the existing
+ * `pendingSelfWrites` window in `core/management-md.ts`. The render +
+ * snapshot step is dominated by JSON serialization and a single small
+ * write, so 5 s is generous; the auto-release exists only as a backstop
+ * against a caller that crashes mid-critical-section without releasing.
+ */
+export declare const MANAGEMENT_MD_WRITE_LOCK_TIMEOUT_MS = 5000;
+export interface ManagementMdWriteLockManager {
+    acquire(): {
+        ok: true;
+        lockId: string;
+    } | {
+        ok: false;
+        holder: string;
+    };
+    release(lockId: string): boolean;
+    isHeldBy(lockId?: string | null): boolean;
+    getHolder(): string | null;
+}
+export declare class InMemoryManagementMdWriteLockManager implements ManagementMdWriteLockManager {
+    private readonly timeoutMs;
+    private holder;
+    private timer;
+    constructor(timeoutMs?: number);
+    acquire(): {
+        ok: true;
+        lockId: string;
+    } | {
+        ok: false;
+        holder: string;
+    };
+    release(lockId: string): boolean;
+    isHeldBy(lockId?: string | null): boolean;
+    getHolder(): string | null;
+}
+/**
+ * Run `fn` while holding the write lock. Releases on both success and
+ * thrown exceptions so a partial render cannot strand the file.
+ *
+ * Returns `null` when the lock is currently held by another caller —
+ * the registry boot path treats this as "another acquirer is mid-write,
+ * skip the boot re-render and let theirs land". The watcher's hot path
+ * uses the same shape to back off cleanly.
+ */
+export declare function withManagementMdWriteLock<T>(manager: ManagementMdWriteLockManager, fn: () => Promise<T> | T): Promise<{
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    holder: string;
+}>;
+//# sourceMappingURL=management-md-write-lock.d.ts.map

package/dist/core/management-md-write-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"management-md-write-lock.d.ts","sourceRoot":"","sources":["../../src/core/management-md-write-lock.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mCAAmC,OAAQ,CAAC;AAEzD,MAAM,WAAW,4BAA4B;IAC3C,OAAO,IAAI;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;IAC1C,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,qBAAa,oCACX,YAAW,4BAA4B;IAK3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAHtC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,KAAK,CAA8C;gBAE9B,SAAS,GAAE,MAA4C;IAEpF,OAAO,IAAI;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAyBvE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAWhC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAKzC,SAAS,IAAI,MAAM,GAAG,IAAI;CAG3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,OAAO,EAAE,4BAA4B,EACrC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CASjE"}

package/dist/core/management-md-write-lock.js

@@ -0,0 +1,93 @@
+import { randomUUID } from "node:crypto";
+import { createLogger } from "../logging.js";
+const logger = createLogger("management-md-write-lock");
+/**
+ * `rules/management.md` write-lock manager — docs/design/21-management-
+ * registry-and-entities.md §11.1.
+ *
+ * Mirrors the {@link InMemoryTodayWriteLockManager} pattern (see
+ * `today-write-lock.ts`): a single in-process holder, an auto-release
+ * timer, and a UUID lock-id that callers MUST present back to release.
+ *
+ * The registry's render+write path acquires the lock for the duration
+ * of (render → atomic write → snapshot) so a competing API write or
+ * boot reconciler cannot interleave between the steps. A single-vault,
+ * single-daemon deployment makes an in-memory lock sufficient — the
+ * file is not edited from a sibling process. If multi-daemon access is
+ * ever introduced, swap the implementation for a `flock(2)`-backed one
+ * matching `migration-lock` semantics.
+ *
+ * Default timeout: 5 s, matching the design's call-out and the existing
+ * `pendingSelfWrites` window in `core/management-md.ts`. The render +
+ * snapshot step is dominated by JSON serialization and a single small
+ * write, so 5 s is generous; the auto-release exists only as a backstop
+ * against a caller that crashes mid-critical-section without releasing.
+ */
+export const MANAGEMENT_MD_WRITE_LOCK_TIMEOUT_MS = 5_000;
+export class InMemoryManagementMdWriteLockManager {
+    timeoutMs;
+    holder = null;
+    timer = null;
+    constructor(timeoutMs = MANAGEMENT_MD_WRITE_LOCK_TIMEOUT_MS) {
+        this.timeoutMs = timeoutMs;
+    }
+    acquire() {
+        if (this.holder) {
+            logger.debug({ existingHolder: this.holder }, "management.md write lock acquire rejected — already held");
+            return { ok: false, holder: this.holder };
+        }
+        const lockId = randomUUID();
+        this.holder = lockId;
+        this.timer = setTimeout(() => {
+            logger.warn({ lockId: this.holder, timeoutMs: this.timeoutMs }, "management.md write lock expired by timeout — releasing");
+            this.holder = null;
+            this.timer = null;
+        }, this.timeoutMs);
+        // The auto-release timer must not pin the event loop in tests or
+        // when the daemon is otherwise quiescent.
+        this.timer.unref?.();
+        logger.debug({ lockId }, "management.md write lock acquired");
+        return { ok: true, lockId };
+    }
+    release(lockId) {
+        if (!this.holder || this.holder !== lockId)
+            return false;
+        this.holder = null;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        logger.debug({ lockId }, "management.md write lock released");
+        return true;
+    }
+    isHeldBy(lockId) {
+        if (!this.holder)
+            return false;
+        return this.holder === lockId;
+    }
+    getHolder() {
+        return this.holder;
+    }
+}
+/**
+ * Run `fn` while holding the write lock. Releases on both success and
+ * thrown exceptions so a partial render cannot strand the file.
+ *
+ * Returns `null` when the lock is currently held by another caller —
+ * the registry boot path treats this as "another acquirer is mid-write,
+ * skip the boot re-render and let theirs land". The watcher's hot path
+ * uses the same shape to back off cleanly.
+ */
+export async function withManagementMdWriteLock(manager, fn) {
+    const acquired = manager.acquire();
+    if (!acquired.ok)
+        return acquired;
+    try {
+        const value = await fn();
+        return { ok: true, value };
+    }
+    finally {
+        manager.release(acquired.lockId);
+    }
+}
+//# sourceMappingURL=management-md-write-lock.js.map

package/dist/core/management-md-write-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"management-md-write-lock.js","sourceRoot":"","sources":["../../src/core/management-md-write-lock.ts"],"names":[],"mappings":"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"}