@mnmal-ai/cortext 0.0.0 → 1.0.0-alpha.1

package/dist/plugin-27UpMnoE.js

@@ -0,0 +1,811 @@
+//#region src/kernel/cortext-namespace.ts
+/**
+* The namespace the kernel invariants are scoped to.
+*
+* Every CHECK constraint and partial index this plugin installs carries a
+* `namespace = <literal>` predicate, so that a kernel-wide table
+* (`rows`) can hold rows for unrelated namespaces without inheriting
+* cortext's controlled vocabularies. That literal has to live in exactly one
+* place, because getting it wrong fails SILENTLY: a constraint scoped to a
+* namespace with no rows is not an error, it is a constraint that passes
+* trivially, and an index whose predicate no query can satisfy is not an
+* error either — it is a heap scan.
+*
+* Tests that seed rows under the namespace the migrations name cannot catch a
+* mismatch with the one production uses, so this constant is the one copy.
+*
+* THE CONFIGURABILITY GAP, and what is actually done about it.
+*
+* The coordinator's namespaces are operator-configurable, while
+* KernelMigrationContext exposes only `sql` and `metric` — a migration
+* cannot read config. So these constants track the DEFAULTS, and a deployment
+* that renames a namespace would get no kernel invariants at all.
+*
+* Parameterising the literals does not fix that. Migrations are recorded once
+* by `id` in migrations and `apply` runs only when the id is absent, so
+* a later rename can never retroactively re-scope objects already created. It
+* would produce correct FRESH installs and silently-wrong RENAMED ones, which
+* is worse than today because it reads as solved.
+*
+* The fix is reconciliation against the configured namespace. `onKernelReady`
+* carries a `sql` handle and plugin-attributed coordinator namespaces, so it
+* is possible, but it is opt-in (`./repair.ts`): a store that ran unscoped may
+* hold rows violating the vocabulary, so `ADD CONSTRAINT` can fail on exactly
+* the databases a repair exists for.
+*
+* So what ships is REPORTING, not reconciliation, in two places that answer
+* different questions: the kernel's `./invariant-audit.ts` reads the catalog
+* at boot (objects absent, misscoped, or NOT VALID), and the coordinator's
+* `onStart` compares the CONFIGURED namespaces against these constants. See
+* `packages/cortext/src/kernel-invariants.ts`.
+*
+* It warns rather than REFUSES. Per-cohort context stores are a designed
+* capability that `bootstrap-config.test.ts` exercises with `codex`, so the
+* override keeps working; only the silence goes.
+*/
+const CORTEXT_NAMESPACE = "cortext";
+/**
+* The namespace the architecture-findings surface registers under, and which
+* migration 0002 scopes its body normalization to.
+*
+* Separate from CORTEXT_NAMESPACE because the two have separate operator
+* knobs and diverging lifecycle policies (compaction, retention, audit) — but
+* subject to exactly the same gap, which is why it is stated here rather than
+* left as a bare literal inside 0002.
+*/
+const ARCHITECTURE_NAMESPACE = "architecture";
+/**
+* The `name` the cortext COORDINATOR plugin registers itself under.
+*
+* Lives here, beside the namespace literals, because it is load-bearing for
+* exactly the same reason they are. The kernel resolves
+* which namespace to target by filtering
+* `KernelLifecycleContext.coordinatorNamespacesByPlugin` on
+* `plugin === CORTEXT_COORDINATOR_NAME` — so if the coordinator is ever
+* renamed and this literal is not, the filter matches nothing and the audit
+* reports "cortext declares no namespace" on a perfectly healthy deployment.
+*
+* A predicate that silently matches nothing is not an error, and a confidently wrong answer is
+* worse here than no answer, because "coordinator absent" reads as a real
+* finding rather than as a broken check.
+*
+* `kernel-namespace-parity.test.ts` asserts the coordinator's actual
+* `plugin.name` equals this. Do not inline the string on either side.
+*/
+const CORTEXT_COORDINATOR_NAME = "cortext";
+/**
+* Body keys cortext's namespaces mirror into `rows` columns, so the
+* cold-start and status filters hit an index. `0001_baseline` creates them.
+*/
+const CORTEXT_PROMOTED_COLUMNS = {
+	archived: {
+		column: "archived",
+		kind: "boolean"
+	},
+	project: {
+		column: "project",
+		kind: "text"
+	},
+	status: {
+		column: "status",
+		kind: "text"
+	},
+	priority: {
+		column: "priority",
+		kind: "text"
+	}
+};
+
+//#endregion
+//#region src/kernel/invariant-audit.ts
+/**
+* Boot-time audit of the kernel invariants this plugin installs.
+*
+* ## What this is, and what it deliberately is not
+*
+* It VERIFIES. It does not repair. Every migration here installs a CHECK
+* constraint or a partial index carrying a `namespace = <literal>` predicate,
+* and a migration is recorded once by `id` — `apply` runs only when that id is
+* absent — so nothing re-examines those objects after the first boot that
+* created them. Between then and now they can be dropped by hand, left NOT
+* VALID by a failed validation, or point at a namespace no coordinator uses.
+* All three fail the same way: writes succeed, queries answer, and the
+* guarantee is simply gone.
+*
+* AgentIdentity.kid uniqueness is what the mailbox's recipient-only trust
+* model rests on. A constraint scoped to a namespace with no rows is not an
+* error; it passes trivially.
+*
+* ## Why this reports rather than repairs
+*
+* Not because repair is impossible — `./repair.ts` does it, using the `sql`
+* handle and the plugin-attributed namespaces, the latter being what makes a
+* rename TARGETABLE rather than merely detectable.
+*
+* The split is deliberate and permanent. Auditing is a read, so it runs on
+* every boot. Repairing is DDL taking ACCESS EXCLUSIVE on `rows`, so it
+* runs only when an operator asks via `SYNOPTIC_CORTEXT_REPAIR`. Keeping them
+* apart means the reporting path can never surprise anyone, and the repair path
+* has exactly one trigger to reason about.
+*
+* The flat `coordinatorNamespaces` this function reads answers "is our literal
+* declared?" but never "what replaced it". `resolveCortextNamespaces` reads the
+* attributed list — and keeps `undefined` from collapsing into `[]`, which would
+* make "too old to answer" read as "answered: none".
+*/
+/**
+* The five objects. Enumerated by hand rather than derived from the migration
+* array, deliberately: a migration's `apply` is opaque SQL text, so anything
+* "derived" would be a regex over it that agrees with reality only by luck.
+* `invariant-audit.test.ts` greps the migration sources for the DDL and fails
+* if this list and the migrations disagree — which is the check that actually
+* holds them together.
+*
+* Note there is no `architecture/*` entry, and that is correct: migration 0002
+* is a one-time body normalisation, not a standing invariant. A drifted
+* architecture namespace means that normalisation never ran for those rows —
+* real, but a different and lesser thing than "kid uniqueness is not held".
+*/
+const INVARIANT_OBJECTS = [
+	{
+		name: "rows_todo_status_check",
+		kind: "constraint",
+		migration: "0001_baseline",
+		guarantee: "Todo.status is restricted to its controlled vocabulary"
+	},
+	{
+		name: "rows_todo_priority_check",
+		kind: "constraint",
+		migration: "0001_baseline",
+		guarantee: "Todo.priority is restricted to its controlled vocabulary"
+	},
+	{
+		name: "rows_agent_message_recipient_idx",
+		kind: "index",
+		migration: "0001_baseline",
+		guarantee: "mailbox inbox reads are index-backed rather than heap scans"
+	},
+	{
+		name: "rows_agent_identity_kid_unique",
+		kind: "index",
+		migration: "0001_baseline",
+		guarantee: "AgentIdentity.kid is unique — the mailbox's recipient-only trust model rests on this"
+	},
+	{
+		name: "rows_agent_message_status_check",
+		kind: "constraint",
+		migration: "0001_baseline",
+		guarantee: "AgentMessage.status is restricted to its controlled vocabulary"
+	},
+	{
+		name: "rows_host_install_key_unique",
+		kind: "index",
+		migration: "0001_baseline",
+		guarantee: "HostInstall.key is unique — one record per host, repo and harness, so the fleet view cannot show duplicates"
+	}
+];
+/**
+* The namespaces the cortext COORDINATOR declared, or `null` when the host
+* cannot say.
+*
+* The three states are genuinely distinct and the middle one is easy to lose:
+*
+*   - `undefined` in  -> `null` out. The host predates
+*     `coordinatorNamespacesByPlugin`. It is not telling us
+*     "none"; it is not telling us anything.
+*   - `[]` in, or no rows for our plugin -> `[]` out. The host DID attribute,
+*     and cortext contributed nothing — it is not loaded.
+*   - rows for our plugin -> those namespaces, in declaration order.
+*
+* The host deliberately does not default `undefined` to `[]`, which would make
+* "too old to answer" read identically to "answered: none". Returning `null`
+* rather than an empty array preserves that distinction.
+*/
+function resolveCortextNamespaces(byPlugin) {
+	if (byPlugin === void 0) return null;
+	return byPlugin.filter((p) => p.plugin === CORTEXT_COORDINATOR_NAME).map((p) => p.namespace);
+}
+/**
+* Whether a coordinator declared the namespace our objects are scoped to, and
+* — when the host attributes — which namespace replaced it.
+*
+* Pure, and the only half that works without a `sql` handle, so it is what runs
+* against the in-memory dataset.
+*
+* Only the context-store literal is checked. `ARCHITECTURE_NAMESPACE` is
+* exported for callers that want it but is not audited here, for the reason in
+* `INVARIANT_OBJECTS`: no catalog object is scoped to it.
+*/
+function auditNamespaceCoverage(coordinatorNamespaces, byPlugin) {
+	if (coordinatorNamespaces.includes("cortext")) return [];
+	const ours = resolveCortextNamespaces(byPlugin);
+	const configured = ours?.[0];
+	if (configured !== void 0) return [{
+		kind: "namespace_drifted",
+		scopedTo: CORTEXT_NAMESPACE,
+		configured
+	}];
+	return [{
+		kind: "namespace_uncovered",
+		scopedTo: CORTEXT_NAMESPACE,
+		declared: coordinatorNamespaces,
+		reason: ours === null ? "host_does_not_attribute" : "coordinator_absent"
+	}];
+}
+/** The namespace a predicate is scoped to, or null if it names none. */
+function scopedNamespace(definition) {
+	return definition.match(/namespace = '([^']*)'(?:::text)?/)?.[1] ?? null;
+}
+/**
+* Read the catalog state of every object on `rows`.
+*
+* Both lookups are RELATION-scoped (`conrelid` / `indrelid` against
+* `'rows'::regclass`) and not by name alone. Constraint names are unique
+* per relation and index names per schema — neither is globally unique — so a
+* by-name lookup silently reads an unrelated object the moment a second schema
+* carries the same name.
+*/
+async function readCatalog(sql) {
+	const rows = /* @__PURE__ */ new Map();
+	const [present] = await sql`SELECT to_regclass('rows') IS NOT NULL AS ok`;
+	if (!present?.ok) return rows;
+	const constraints = await sql`
+    SELECT conname AS name, pg_get_constraintdef(oid) AS definition, convalidated AS validated
+      FROM pg_constraint
+     WHERE conrelid = 'rows'::regclass
+  `;
+	for (const r of constraints) rows.set(r.name, r);
+	const indexes = await sql`
+    SELECT c.relname AS name, pg_get_indexdef(i.indexrelid) AS definition, i.indisvalid AS validated
+      FROM pg_index i
+      JOIN pg_class c ON c.oid = i.indexrelid
+     WHERE i.indrelid = 'rows'::regclass
+  `;
+	for (const r of indexes) rows.set(r.name, r);
+	return rows;
+}
+/**
+* Audit every object's presence, scope and validity.
+*
+* `sql` is typed `unknown` on the lifecycle context (substrate keeps the driver out
+* of its type surface), so the cast happens here, once, exactly as the
+* migrations do it.
+*/
+/**
+* Audit the invariant objects.
+*
+* Returns the INSPECTED COUNT alongside the findings.
+*
+* A tally rather than `INVARIANT_OBJECTS.length`, so that if this loop ever
+* gains a filter, an early return or a per-object skip, the completion metric
+* reports what was actually inspected instead of a promise.
+*/
+async function auditObjects(sql) {
+	const catalog = await readCatalog(sql);
+	const findings = [];
+	let checked = 0;
+	for (const object of INVARIANT_OBJECTS) {
+		checked++;
+		const row = catalog.get(object.name);
+		if (!row) {
+			findings.push({
+				kind: "object_missing",
+				object
+			});
+			continue;
+		}
+		const scope = scopedNamespace(row.definition);
+		if (scope !== "cortext") {
+			findings.push({
+				kind: "object_misscoped",
+				object,
+				scopedTo: scope
+			});
+			continue;
+		}
+		if (!row.validated) findings.push({
+			kind: "object_not_validated",
+			object
+		});
+	}
+	return {
+		findings,
+		checked
+	};
+}
+/** The operator-facing sentence for one finding. */
+function findingMessage(finding) {
+	const head = "[cortext-kernel]";
+	switch (finding.kind) {
+		case "namespace_drifted": return `${head} the cortext coordinator is configured for namespace '${finding.configured}', but every kernel constraint and index is scoped to '${finding.scopedTo}'. So all of them are INACTIVE for '${finding.configured}': Todo/AgentMessage vocabularies unenforced, the mailbox inbox index covering no rows, and AgentIdentity.kid uniqueness NOT held. Writes succeed and queries answer, so nothing else will report this. Use '${finding.scopedTo}', or accept the loss deliberately.`;
+		case "namespace_uncovered": return `${head} invariants are scoped to namespace '${finding.scopedTo}', which no loaded coordinator declares (declared: ${finding.declared.join(", ") || "none"}). Every kernel guarantee below is therefore INACTIVE, and nothing else will report it — a constraint scoped to a namespace with no rows passes trivially. ` + (finding.reason === "host_does_not_attribute" ? "This substrate does not attribute namespaces to their plugin (added in 5.1.0), so which namespace REPLACED it cannot be determined — upgrade the binary to get a named target rather than this list." : "This substrate does attribute, and the cortext coordinator declared no namespace at all — it is not loaded. The objects are orphaned rather than misscoped.") + " Set SYNOPTIC_CORTEXT_REPAIR=1 for one restart to re-scope.";
+		case "object_missing": return `${head} ${finding.object.kind} '${finding.object.name}' (${finding.object.migration}) is ABSENT. Lost guarantee: ${finding.object.guarantee}. Migrations are recorded once by id, so this will NOT be reinstalled by a restart.`;
+		case "object_misscoped": return `${head} ${finding.object.kind} '${finding.object.name}' is scoped to ${finding.scopedTo === null ? "no namespace" : `'${finding.scopedTo}'`}, not '${CORTEXT_NAMESPACE}'. Lost guarantee: ${finding.object.guarantee}. It exists, so nothing errors; it simply matches no rows.`;
+		case "object_not_validated": return `${head} ${finding.object.kind} '${finding.object.name}' exists but is NOT VALID — enforced for new writes only, and existing rows were never checked against it. Guarantee held only going forward: ${finding.object.guarantee}.`;
+	}
+}
+/**
+* Run the audit and report. Returns the findings so a caller — or a test — can
+* assert on them without capturing the console.
+*
+* Both sinks: `metric` is the structured
+* channel an operator alerts on, and the console line is what actually appears
+* in the server journal beside substrate's own loader warnings, which is
+* where someone will see it.
+*
+* Never throws. A kernel plugin that aborts the boot over an OBSERVATION
+* would take the service down for a condition the service has been running
+* with, possibly for weeks — the whole point is that these failures are silent
+* and survivable. A catalog read that itself fails is reported and swallowed.
+*
+* ## It always emits, including when it finds nothing
+*
+* Every OTHER metric here names a failure, so without a completion signal a
+* clean audit and an audit that never ran would both be silence. A check whose
+* PASS state is indistinguishable from its absence is not falsifiable.
+*
+* So `invariant_audit_complete` fires on every path that reaches the end,
+* carrying `checked`. Silence now means the audit DID NOT RUN and is
+* actionable, and a `checked` that drops from 5 to 4 is visible without
+* anything having failed. Metric only, not a console line: a per-boot success
+* message on every deployment is noise, and the metric sink is exactly the
+* structured channel this belongs in.
+*/
+async function reportInvariantAudit(ctx, warn = console.warn) {
+	const findings = [...auditNamespaceCoverage(ctx.coordinatorNamespaces, ctx.coordinatorNamespacesByPlugin)];
+	const catalogRead = ctx.sql !== null && ctx.sql !== void 0;
+	let objectsChecked = 0;
+	if (catalogRead) try {
+		const result = await auditObjects(ctx.sql);
+		findings.push(...result.findings);
+		objectsChecked = result.checked;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		ctx.metric("cortext_kernel.invariant_audit_failed", { error: message });
+		warn(`[cortext-kernel] could not audit kernel invariants: ${message}. This is the audit failing, NOT the invariants — their state is now unknown.`);
+		return findings;
+	}
+	for (const finding of findings) {
+		ctx.metric("cortext_kernel.invariant_inactive", {
+			finding: finding.kind,
+			object: "object" in finding ? finding.object.name : void 0,
+			scopedTo: "scopedTo" in finding ? finding.scopedTo : void 0,
+			configured: "configured" in finding ? finding.configured : void 0,
+			reason: "reason" in finding ? finding.reason : void 0
+		});
+		warn(findingMessage(finding));
+	}
+	ctx.metric("cortext_kernel.invariant_audit_complete", {
+		checked: objectsChecked,
+		findings: findings.length,
+		catalogRead
+	});
+	return findings;
+}
+
+//#endregion
+//#region src/kernel/todo-vocab.ts
+/**
+* Todo lifecycle and outcome, split. A single `status` doing both jobs makes
+* `done` vs `closed` a grey distinction nobody can apply consistently.
+*
+* LIFECYCLE (`status`): is it live? OUTCOME (`resolution`): why did it stop?
+* The same split GitHub (state + state_reason) and Jira (status + resolution)
+* make.
+*
+* The pg CHECK admits exactly the lifecycle set; `done` / `not_started` are
+* aliases the schema canonicalises on write.
+*/
+const TODO_LIFECYCLE_VOCAB = [
+	"open",
+	"in_progress",
+	"blocked",
+	"deferred",
+	"closed"
+];
+/** Why a closed Todo stopped. `unspecified` is for migrated rows with no clear cue. */
+const TODO_RESOLUTION_VOCAB = [
+	"completed",
+	"wont_do",
+	"superseded",
+	"duplicate",
+	"obsolete",
+	"unspecified"
+];
+const TODO_PRIORITY_VOCAB = [
+	"low",
+	"medium",
+	"high"
+];
+/** AgentMessage delivery state; the pg CHECK and the field enum share it. */
+const AGENT_MESSAGE_STATUS_VOCAB = [
+	"unread",
+	"read",
+	"acked"
+];
+
+//#endregion
+//#region src/kernel/rescope.ts
+const literal = (vocab) => vocab.map((v) => `'${v}'`).join(",");
+const VOCAB_CONSTRAINTS = [
+	{
+		constraint: "rows_todo_priority_check",
+		type: "Todo",
+		column: "priority",
+		vocab: TODO_PRIORITY_VOCAB
+	},
+	{
+		constraint: "rows_todo_status_check",
+		type: "Todo",
+		column: "status",
+		vocab: TODO_LIFECYCLE_VOCAB
+	},
+	{
+		constraint: "rows_agent_message_status_check",
+		type: "AgentMessage",
+		column: "status",
+		vocab: AGENT_MESSAGE_STATUS_VOCAB
+	}
+];
+/**
+* Re-scope one vocabulary CHECK to `namespace`.
+*
+* Returns the number of existing rows that violate it — 0 means VALIDATE
+* succeeded and the constraint is fully enforced; >0 means it was left NOT
+* VALID (enforcing new writes only) and an operator has rows to reconcile.
+*
+* The NOT VALID -> validate-inside-a-handler shape is what makes this safe to
+* run against a store that has been writing UNCONSTRAINED. A plain
+* `ADD CONSTRAINT ... CHECK` validates immediately and therefore fails on
+* exactly the databases a repair exists for — the ones that drifted long
+* enough to accumulate bad rows.
+*/
+async function rescopeVocabConstraint(s, metric, { constraint, type, column, vocab }, namespace) {
+	const values = literal(vocab);
+	const [violation] = await s.unsafe(`
+    SELECT count(*)::int AS count FROM rows
+     WHERE namespace = '${namespace}'
+       AND type = '${type}'
+       AND ${column} IS NOT NULL
+       AND ${column} NOT IN (${values})
+  `);
+	const violations = violation?.count ?? 0;
+	await s.unsafe(`ALTER TABLE rows DROP CONSTRAINT IF EXISTS ${constraint}`);
+	await s.unsafe(`
+    ALTER TABLE rows
+      ADD CONSTRAINT ${constraint}
+        CHECK (
+          NOT (namespace = '${namespace}' AND type = '${type}')
+          OR ${column} IS NULL
+          OR ${column} IN (${values})
+        ) NOT VALID
+  `);
+	await s.unsafe(`
+    DO $$ BEGIN
+      IF EXISTS (
+        SELECT 1 FROM pg_constraint
+        WHERE conname = '${constraint}'
+          AND conrelid = 'rows'::regclass AND NOT convalidated
+      ) THEN
+        BEGIN
+          ALTER TABLE rows VALIDATE CONSTRAINT ${constraint};
+        EXCEPTION WHEN check_violation THEN
+          RAISE WARNING 'cortext-kernel: % left NOT VALID — existing rows violate it; new writes are still enforced', '${constraint}';
+        END;
+      END IF;
+    END $$
+  `);
+	if (violations > 0) metric("cortext_kernel.rescope.constraint_not_validated", {
+		constraint,
+		type,
+		column,
+		namespace,
+		violations
+	});
+	return violations;
+}
+/**
+* Re-scope the mailbox inbox index (0003) to `namespace`.
+*
+* Dropped and rebuilt rather than left alongside a correctly-scoped sibling:
+* two partial indexes over the same expression is one the planner can never
+* use, plus write amplification on every AgentMessage insert.
+*/
+async function rescopeRecipientIndex(s, namespace) {
+	await s.unsafe("DROP INDEX IF EXISTS rows_agent_message_recipient_idx");
+	await s.unsafe(`
+    CREATE INDEX IF NOT EXISTS rows_agent_message_recipient_idx
+      ON rows ((body->>'recipient'), status)
+      WHERE namespace = '${namespace}'
+        AND type = 'AgentMessage'
+        AND deleted_at IS NULL
+        AND archived IS NOT TRUE
+  `);
+}
+/**
+* How many kids would collide if the unique index were scoped to `namespace`.
+*
+* Exposed separately because a UNIQUE index has no `NOT VALID` equivalent —
+* there is no "enforce for new writes only" state for an index. `CREATE UNIQUE
+* INDEX` either succeeds over the whole predicate or fails outright, so the
+* only way to avoid failing is to ask first. That asymmetry with the CHECK
+* constraints is why repair treats the two differently.
+*
+* The predicate matches `rescopeKidUniqueIndex`'s exactly, including the
+* tombstone exemption — an archived duplicate is still a conflict, and hard-
+* deleting a retired identity frees its kid.
+*/
+async function countDuplicateKids(s, namespace) {
+	const [row] = await s.unsafe(`
+    SELECT count(*)::int AS count FROM (
+      SELECT body->>'kid' AS kid
+        FROM rows
+       WHERE namespace = '${namespace}'
+         AND type = 'AgentIdentity'
+         AND deleted_at IS NULL
+       GROUP BY body->>'kid'
+      HAVING count(*) > 1
+    ) dupes
+  `);
+	return row?.count ?? 0;
+}
+/**
+* Re-scope the AgentIdentity.kid unique index (0004) to `namespace`.
+*
+* THROWS on duplicate kids, and that is deliberate — it preserves 0004's
+* fail-loud stance, because recipient resolution and the mailbox's
+* recipient-only enforcement are both ambiguous until an operator decides
+* which row owns the identity. Callers that must not abort should call
+* `countDuplicateKids` first; the repair path does.
+*/
+async function rescopeKidUniqueIndex(s, namespace) {
+	await s.unsafe("DROP INDEX IF EXISTS rows_agent_identity_kid_unique");
+	await s.unsafe(`
+    CREATE UNIQUE INDEX IF NOT EXISTS rows_agent_identity_kid_unique
+      ON rows ((body->>'kid'))
+      WHERE namespace = '${namespace}'
+        AND type = 'AgentIdentity'
+        AND deleted_at IS NULL
+  `);
+}
+/**
+* How many HostInstall keys would collide if the unique index were scoped to
+* `namespace`. Asked first for the same reason as `countDuplicateKids`.
+*/
+async function countDuplicateHostInstallKeys(s, namespace) {
+	const [row] = await s.unsafe(`
+    SELECT count(*)::int AS count FROM (
+      SELECT body->>'key' AS key
+        FROM rows
+       WHERE namespace = '${namespace}'
+         AND type = 'HostInstall'
+         AND deleted_at IS NULL
+       GROUP BY body->>'key'
+      HAVING count(*) > 1
+    ) dupes
+  `);
+	return row?.count ?? 0;
+}
+/**
+* Re-scope the HostInstall.key unique index (0008) to `namespace`. Throws on
+* duplicate keys; callers that must not abort call
+* `countDuplicateHostInstallKeys` first.
+*/
+async function rescopeHostInstallKeyIndex(s, namespace) {
+	await s.unsafe("DROP INDEX IF EXISTS rows_host_install_key_unique");
+	await s.unsafe(`
+    CREATE UNIQUE INDEX IF NOT EXISTS rows_host_install_key_unique
+      ON rows ((body->>'key'))
+      WHERE namespace = '${namespace}'
+        AND type = 'HostInstall'
+        AND deleted_at IS NULL
+  `);
+}
+
+//#endregion
+//#region src/kernel/migrations/0001_baseline.ts
+const cortextBaselineMigration = {
+	id: "0001_baseline",
+	apply: async ({ sql, metric }) => {
+		if (sql === null) return;
+		const s = sql;
+		await s.unsafe(`
+      ALTER TABLE rows
+        ADD COLUMN IF NOT EXISTS archived boolean NOT NULL DEFAULT false,
+        ADD COLUMN IF NOT EXISTS project  text    NULL,
+        ADD COLUMN IF NOT EXISTS status   text    NULL,
+        ADD COLUMN IF NOT EXISTS priority text    NULL
+    `);
+		for (const column of [
+			"archived",
+			"project",
+			"status",
+			"priority"
+		]) await s.unsafe(`
+        CREATE INDEX IF NOT EXISTS rows_ns_type_${column}_idx
+          ON rows (namespace, type, ${column}) WHERE deleted_at IS NULL
+      `);
+		await s.unsafe(`
+      CREATE INDEX IF NOT EXISTS rows_cold_start_idx
+        ON rows (namespace, type, project)
+        WHERE deleted_at IS NULL AND archived IS NOT TRUE
+    `);
+		for (const spec of VOCAB_CONSTRAINTS) await rescopeVocabConstraint(s, metric, spec, CORTEXT_NAMESPACE);
+		await rescopeRecipientIndex(s, CORTEXT_NAMESPACE);
+		await rescopeKidUniqueIndex(s, CORTEXT_NAMESPACE);
+		await rescopeHostInstallKeyIndex(s, CORTEXT_NAMESPACE);
+	},
+	rollback: async ({ sql }) => {
+		if (sql === null) return;
+		const s = sql;
+		for (const { constraint } of VOCAB_CONSTRAINTS) await s.unsafe(`ALTER TABLE rows DROP CONSTRAINT IF EXISTS ${constraint}`);
+		await s.unsafe("DROP INDEX IF EXISTS rows_agent_identity_kid_unique, rows_host_install_key_unique");
+		await s.unsafe("ALTER TABLE rows DROP COLUMN IF EXISTS archived, DROP COLUMN IF EXISTS project, DROP COLUMN IF EXISTS status, DROP COLUMN IF EXISTS priority");
+	}
+};
+
+//#endregion
+//#region src/kernel/repair.ts
+/** The env var that opts a deployment in, for one restart. */
+const REPAIR_ENV_VAR = "SYNOPTIC_CORTEXT_REPAIR";
+/**
+* Whether repair was asked for.
+*
+* Accepts only the affirmative spellings an operator would plausibly type, and
+* treats everything else — including `0` and `false` — as off. Deliberately not
+* a truthiness check on the raw string: `SYNOPTIC_CORTEXT_REPAIR=false` is
+* unambiguously a request NOT to repair, and a bare presence check would read
+* it as a yes and re-scope a production schema.
+*/
+function repairRequested(env) {
+	const raw = env[REPAIR_ENV_VAR]?.trim().toLowerCase();
+	return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+/**
+* Re-scope every invariant object to `namespace`.
+*
+* Constraints first, then indexes — the constraints are
+* the correctness-bearing half and should land even if an index cannot.
+*/
+async function repairInvariants(sql, metric, namespace) {
+	const s = sql;
+	const outcomes = [];
+	for (const spec of VOCAB_CONSTRAINTS) {
+		const violations = await rescopeVocabConstraint(s, metric, spec, namespace);
+		outcomes.push(violations > 0 ? {
+			kind: "repaired_not_validated",
+			object: spec.constraint,
+			violations
+		} : {
+			kind: "repaired",
+			object: spec.constraint
+		});
+	}
+	await rescopeRecipientIndex(s, namespace);
+	outcomes.push({
+		kind: "repaired",
+		object: "rows_agent_message_recipient_idx"
+	});
+	const duplicates = await countDuplicateKids(s, namespace);
+	if (duplicates > 0) outcomes.push({
+		kind: "skipped",
+		object: "rows_agent_identity_kid_unique",
+		reason: `${duplicates} kid(s) are held by more than one live AgentIdentity in '${namespace}', so a unique index cannot be built. Recipient resolution is ambiguous until an operator decides which row owns each identity — resolve the duplicates, then re-run repair. The existing index is left exactly as it was.`
+	});
+	else {
+		await rescopeKidUniqueIndex(s, namespace);
+		outcomes.push({
+			kind: "repaired",
+			object: "rows_agent_identity_kid_unique"
+		});
+	}
+	const duplicateKeys = await countDuplicateHostInstallKeys(s, namespace);
+	if (duplicateKeys > 0) outcomes.push({
+		kind: "skipped",
+		object: "rows_host_install_key_unique",
+		reason: `${duplicateKeys} HostInstall key(s) are held by more than one live row in '${namespace}', so a unique index cannot be built. Delete the older row for each key, then re-run repair. The existing index is left exactly as it was.`
+	});
+	else {
+		await rescopeHostInstallKeyIndex(s, namespace);
+		outcomes.push({
+			kind: "repaired",
+			object: "rows_host_install_key_unique"
+		});
+	}
+	return outcomes;
+}
+/** The operator-facing sentence for one outcome. */
+function repairOutcomeMessage(outcome, namespace) {
+	const head = "[cortext-kernel]";
+	switch (outcome.kind) {
+		case "repaired": return `${head} re-scoped '${outcome.object}' to namespace '${namespace}'.`;
+		case "repaired_not_validated": return `${head} re-scoped '${outcome.object}' to '${namespace}', but left it NOT VALID: ${outcome.violations} existing row(s) violate it. New writes ARE enforced; the existing rows are not, and will not be until they are corrected and the constraint validated.`;
+		case "skipped": return `${head} could NOT repair '${outcome.object}'. ${outcome.reason}`;
+	}
+}
+/**
+* Run repair if asked, and report. Returns null when it did not run, so a
+* caller can tell "declined" from "ran and found nothing to do".
+*
+* Never throws, for the same reason the audit does not: this is invoked during
+* boot, and a failure here must degrade to a report rather than take down a
+* service that was running fine — badly, but fine — a moment earlier.
+*/
+async function repairIfRequested(ctx, warn = console.warn) {
+	if (!repairRequested(ctx.env)) return null;
+	if (ctx.sql === null || ctx.sql === void 0) {
+		warn(`[cortext-kernel] ${REPAIR_ENV_VAR} is set, but this binary has no SQL handle (in-memory dataset). Nothing to repair.`);
+		return null;
+	}
+	if (ctx.namespace === null) {
+		warn(`[cortext-kernel] ${REPAIR_ENV_VAR} is set, but the target namespace cannot be determined: this substrate does not attribute namespaces to their plugin (added in 5.1.0), or the cortext coordinator is not loaded. Repair DECLINED — it will not guess which namespace to re-scope to. Upgrade the binary, or run against a host that reports coordinatorNamespacesByPlugin.`);
+		ctx.metric("cortext_kernel.repair_declined", { reason: "target_unknown" });
+		return null;
+	}
+	warn(`[cortext-kernel] ${REPAIR_ENV_VAR} is set — re-scoping kernel invariants to '${ctx.namespace}'. This takes ACCESS EXCLUSIVE on rows and briefly blocks writes.` + (ctx.namespace === "cortext" ? " Target matches the built-in scope literal, so this is a no-op rebuild." : ""));
+	try {
+		const outcomes = await repairInvariants(ctx.sql, ctx.metric, ctx.namespace);
+		for (const outcome of outcomes) {
+			ctx.metric("cortext_kernel.repair_outcome", {
+				outcome: outcome.kind,
+				object: outcome.object,
+				namespace: ctx.namespace
+			});
+			warn(repairOutcomeMessage(outcome, ctx.namespace));
+		}
+		warn(`[cortext-kernel] repair complete. Unset ${REPAIR_ENV_VAR} — leaving it set re-runs this DDL on every boot, which is the automatic behaviour opt-in exists to avoid.`);
+		return outcomes;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		ctx.metric("cortext_kernel.repair_failed", {
+			error: message,
+			namespace: ctx.namespace
+		});
+		warn(`[cortext-kernel] repair FAILED: ${message}. Some objects may have been re-scoped and others not — re-run the audit (restart without the env var) to see the current state.`);
+		return null;
+	}
+}
+
+//#endregion
+//#region src/kernel/substrate-contract.ts
+/**
+* The range of substrate versions both cortext plugins are built against.
+*
+* ONE literal, used in two places that must never disagree:
+*
+*   1. `contractVersion` on both plugin objects, checked by the substrate
+*      loader at boot, which refuses a plugin outside it.
+*   2. The `@mnmal-ai/substrate` peer range in the manifest, checked by the
+*      package manager at install.
+*
+* Both exist because they guard different paths: `SUBSTRATE_PLUGIN_DIR` scans
+* a directory, so a plugin dropped in by hand never meets a package manager,
+* and the loader check is all that is left.
+*
+* The ceiling tracks actual plugin-facing compatibility, not the next major
+* by reflex: widen it only after reading what the new major changed.
+* `substrate-contract-parity.test.ts` holds the manifest to this literal.
+*/
+const SUBSTRATE_CONTRACT_RANGE = ">=1.0.0-alpha.0 <2.0.0";
+
+//#endregion
+//#region src/kernel/plugin.ts
+function createCortextKernelPlugin() {
+	return {
+		name: "cortext-kernel",
+		contractVersion: SUBSTRATE_CONTRACT_RANGE,
+		onKernelReady: async (ctx) => {
+			await reportInvariantAudit(ctx);
+			await repairIfRequested({
+				sql: ctx.sql,
+				namespace: resolveCortextNamespaces(ctx.coordinatorNamespacesByPlugin)?.[0] ?? null,
+				env: process.env,
+				metric: ctx.metric
+			});
+		},
+		migrations: [cortextBaselineMigration]
+	};
+}
+
+//#endregion
+export { CORTEXT_PROMOTED_COLUMNS as A, findingMessage as C, ARCHITECTURE_NAMESPACE as D, scopedNamespace as E, CORTEXT_COORDINATOR_NAME as O, auditObjects as S, resolveCortextNamespaces as T, TODO_LIFECYCLE_VOCAB as _, repairInvariants as a, INVARIANT_OBJECTS as b, cortextBaselineMigration as c, countDuplicateKids as d, rescopeHostInstallKeyIndex as f, AGENT_MESSAGE_STATUS_VOCAB as g, rescopeVocabConstraint as h, repairIfRequested as i, CORTEXT_NAMESPACE as k, VOCAB_CONSTRAINTS as l, rescopeRecipientIndex as m, SUBSTRATE_CONTRACT_RANGE as n, repairOutcomeMessage as o, rescopeKidUniqueIndex as p, REPAIR_ENV_VAR as r, repairRequested as s, createCortextKernelPlugin as t, countDuplicateHostInstallKeys as u, TODO_PRIORITY_VOCAB as v, reportInvariantAudit as w, auditNamespaceCoverage as x, TODO_RESOLUTION_VOCAB as y };