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

package/dist/mailbox.d.ts

@@ -0,0 +1,80 @@
+/**
+ * claude/AgentMessage mutation family — the mailbox write + transition surface.
+ *
+ * Three custom mutations replace the autoCRUD write paths for AgentMessage:
+ *
+ *   - `sendAgentMessage`  — kid-addressed send with fan-out. `to` accepts a
+ *     single kid, a list of kids, or `'*'` (every active AgentIdentity except
+ *     the sender). One row per recipient; `recipient: null` broadcasts are
+ *     retired (cohort-global read-state made the first reader hide an
+ *     announcement from everyone else).
+ *   - `markAgentMessageRead` / `ackAgentMessage` — recipient-only status
+ *     transitions. Ack stamps `ackedBy` / `ackedAt` server-side so attribution
+ *     survives later row edits (`updatedBy` is too coarse: any field update
+ *     smudges it).
+ *
+ * Direct `createAgentMessage` is not registered at all — AgentMessage declares
+ * `autoCrud: false`, so the published schema cannot advertise a mutation the
+ * route only denies (a caller reading the schema built a shape that could never
+ * work, and the refusal looked like a grant problem). `mailboxWriteGuard` still
+ * denies transition-field patches through `updateAgentMessage`, and keeps its
+ * create branch as the second line of defence for any path that re-registers
+ * the verb — the mutation family remains the only write path, which is what
+ * enforces kid addressing rather than documenting it.
+ *
+ * The sender remains `_metadata.createdBy` (server-stamped from the signed
+ * principal; spec §3) — fan-out does not change the trust model.
+ */
+import type { FieldDef, NamespaceInstallContext, Policy } from '@mnmal-ai/substrate/sdk';
+/**
+ * Policy over AgentMessage's hand-registered surface — `installMailboxMutations`
+ * composes it with the plugin policy, the way defineNamespace composes type
+ * policies for autoCRUD types. Retires the direct write paths:
+ *   - create → always denied. The verb is not registered (autoCrud:false), so
+ *     this branch only fires if something re-registers it; the schema never
+ *     advertises it.
+ *   - update → only archived and tags may change; a transition field
+ *     or anything fixed at send is denied, each with its own reason.
+ */
+export declare const mailboxWriteGuard: Policy;
+/**
+ * Resolve the `to` param into directory rows, validate-first so a bad address
+ * rejects before any row is written:
+ *   - wildcard (`['*']` canonical; bare `'*'` accepted as sugar) → every
+ *     active identity except the sender; empty → no_recipients. Mixing the
+ *     wildcard with explicit kids is ambiguous → wildcard_mixed.
+ *   - kid / kid[] → deduped; unknown kid → unknown_recipient; inactive →
+ *     inactive_recipient.
+ */
+/**
+ * Whether `to:'*'` should fan a copy out to this identity.
+ *
+ * ABSENT AND NULL BOTH MEAN ELIGIBLE, and that is the whole reason this is a
+ * predicate rather than a `where` clause. `broadcastEligible` is declared
+ * `default: true`, but a default is applied on WRITE — every AgentIdentity row
+ * created before the field existed carries no such key and reads back as
+ * `null`.
+ *
+ * So `where: { broadcastEligible: { eq: true } }` would match NONE of them
+ * (and `eq: null` matches nothing either, under SQL three-valued logic),
+ * turning every broadcast into `no_recipients`. Opting OUT has to be an
+ * explicit `false`.
+ *
+ * Exported because it cannot be exercised through `createAgentIdentity`: that
+ * path applies the declared default, so a row written through the schema always
+ * carries the key. The pre-field shape is only reachable directly, which is
+ * what `mailbox-broadcast-eligibility.test.ts` does.
+ */
+export declare function isBroadcastEligible(row: Record<string, unknown>): boolean;
+/**
+ * Register AgentMessage's whole surface. The type declares `autoCrud: false`,
+ * so defineNamespace installed nothing for it and this function owns the lot:
+ * the type entry, get/update/delete — same resolvers and same params/returns
+ * installAutoCrud would have emitted — plus the custom family (sendAgentMessage,
+ * markAgentMessageRead, ackAgentMessage). What is deliberately absent is
+ * `createAgentMessage`: an advertised mutation the route only denies teaches
+ * callers to build a shape that cannot work, and the refusal reads like a
+ * grant problem. Field defs arrive pre-augmentation; the reserved engine
+ * fields are added here, the way defineNamespace adds them for autoCRUD types.
+ */
+export declare function installMailboxMutations(ctx: NamespaceInstallContext, messageFields: Record<string, FieldDef>): void;

package/dist/namespace.d.ts

@@ -0,0 +1,159 @@
+/**
+ * cortext namespace definition. Spec: §5.11, §6.1.
+ *
+ * The context-store types (SessionLog, Decision, Todo, AgentRule,
+ * CouncilSession, CouncilAdvisor, Memory, AnchorIntent, Concept, ConceptLink,
+ * Skill) on the `defineNamespace` helper, plus the agent-to-agent messaging
+ * surface (AgentIdentity directory + AgentMessage mailbox). Notes:
+ *   - There is no `{ upsert: true }` namespace option — `write` is upsert by
+ *     default.
+ *   - There is no per-type `deletable: true` — autoCRUD always installs
+ *     `delete<T>`.
+ *   - FK-shaped fields are first-class `field.crossRef` edges with explicit
+ *     onDelete policies.
+ *
+ * Embeddable types declare `embed.source` metadata; substrate's recall plugin
+ * walks this at compose time and chains an embedding postWrite per match.
+ */
+import type { NamespaceDefinition } from '@mnmal-ai/substrate/sdk';
+/**
+ * Decision lifecycle states this vocabulary DOCUMENTS. ADVISORY, not enforced,
+ * like `AgentRule.category`. This is a list, not a census: nothing reconciles
+ * it against the store, so it never claims what is "in use".
+ *
+ * A free string is the honest encoding of a taxonomy nobody designed. An enum
+ * freezes it, and agents then either invent undeclared synonyms or pick the
+ * nearest legal word. `open` names a decision recorded before it was made.
+ *
+ * Nothing branches on `status` today (cold-start projects and renders it), but
+ * that is not the argument: `status` is a conventionally mechanical name, so a
+ * future consumer is likely to branch on it.
+ *
+ * THE DIRECTION MATTERS. Widening cannot invalidate stored data; it only
+ * surprises readers. Narrowing STRANDS rows — readable, not round-trippable,
+ * and selectively so, since a partial update avoiding the field still succeeds
+ * while a read-modify-write client gets `invalid_enum_value` on a row it never
+ * touched. So re-adding `field.enum` here later is not a symmetric undo. Do
+ * not do it.
+ *
+ * Add to this list when a genuinely NEW state earns its place; it feeds the
+ * onboarding contract, so what is here is what an agent is taught. `accepted`
+ * is deliberately an alias of `active` rather than a state of its own.
+ */
+export declare const DECISION_STATUS_VOCAB: readonly ['open', 'active', 'superseded', 'deferred'];
+/**
+ * Synonyms the server normalises on every write and filter. `field.vocab` with
+ * `strict: false` is NOT the enum warned against above: unknown values are
+ * still admitted, so nothing narrows and nothing strands. It only maps the
+ * words agents reach for onto the state they mean. `proposed` is a decision
+ * recorded before it was made, which is what `open` documents.
+ */
+export declare const DECISION_STATUS_ALIASES: {
+    readonly accepted: 'active';
+    readonly adopted: 'active';
+    readonly decided: 'active';
+    readonly proposed: 'open';
+};
+/**
+ * Words agents reach for when a Todo stops, mapped onto lifecycle + outcome.
+ * Each closing word sets `status: closed` AND the resolution it
+ * means, so `status: done` still works and now records WHY. A caller that
+ * also sends a contradicting `resolution` is refused (`conflicting_implication`).
+ */
+export declare const TODO_STATUS_ALIASES: {
+    readonly done: 'closed';
+    readonly finished: 'closed';
+    readonly completed: 'closed';
+    readonly shipped: 'closed';
+    readonly cancelled: 'closed';
+    readonly dropped: 'closed';
+    readonly superseded: 'closed';
+    readonly not_started: 'open';
+};
+export declare const TODO_STATUS_IMPLIES: {
+    readonly done: {
+        readonly resolution: 'completed';
+    };
+    readonly finished: {
+        readonly resolution: 'completed';
+    };
+    readonly completed: {
+        readonly resolution: 'completed';
+    };
+    readonly shipped: {
+        readonly resolution: 'completed';
+    };
+    readonly cancelled: {
+        readonly resolution: 'wont_do';
+    };
+    readonly dropped: {
+        readonly resolution: 'wont_do';
+    };
+    readonly superseded: {
+        readonly resolution: 'superseded';
+    };
+};
+export declare const TODO_RESOLUTION_ALIASES: {
+    readonly done: 'completed';
+    readonly shipped: 'completed';
+    readonly wontfix: 'wont_do';
+    readonly declined: 'wont_do';
+    readonly dup: 'duplicate';
+    readonly moot: 'obsolete';
+};
+/**
+ * AgentRule severity — CLOSED, unlike `category`. Cold-start branches on it:
+ * `must` rules render in the binding brief. `high` and `medium` are aliases
+ * rather than stranded values.
+ */
+export declare const AGENT_RULE_SEVERITY_VOCAB: readonly ['must', 'should'];
+export declare const AGENT_RULE_SEVERITY_ALIASES: {
+    readonly high: 'must';
+    readonly medium: 'should';
+};
+/**
+ * AgentRule categories. ADVISORY, not enforced.
+ *
+ * An enum here arrives narrower than the data and freezes the taxonomy. The
+ * damage is not a write rejection anyone notices but SILENT SUBSTITUTION:
+ * agents pick the nearest legal word and move on, and the taxonomy flattens
+ * toward whatever is allowed. Nothing consumes `category` mechanically —
+ * cold-start projects it and renders it, never groups or filters on it — and
+ * `ArchitectureConcern.category` in this same file is a free string too.
+ * Widening an enum would only move the wall to the next category.
+ *
+ * Add to this list when a genuinely new category earns its place; it feeds the
+ * onboarding contract so agents see the real taxonomy. Do NOT re-add
+ * `field.enum` over it.
+ */
+export declare const AGENT_RULE_CATEGORY_VOCAB: readonly ['git', 'testing', 'style', 'process', 'tooling', 'communication', 'investigation', 'migration-patterns', 'permissions', 'scope-discipline', 'side-findings', 'verification'];
+/**
+ * AgentMessage.status vocabulary single-sources from the kernel sibling
+ * — the same constant drives both the field.enum guard here and
+ * the kernel CHECK constraint, matching the TODO_*_VOCAB pattern. Re-exported
+ * so this module's surface carries it.
+ */
+export { AGENT_MESSAGE_STATUS_VOCAB } from './kernel/index.js';
+/**
+ * HostInstall.fragmentState: the cold-start fragment drift check's own verdict,
+ * plus `source` for the repo that ships the fragment.
+ */
+export declare const HOST_INSTALL_FRAGMENT_STATES: readonly ['current', 'stale', 'missing', 'undigested', 'uncomparable', 'source', 'absent'];
+/** HostInstall's per-check verdicts: the worst finding each check produced. */
+export declare const HOST_INSTALL_CHECK_STATES: readonly ['ok', 'warn', 'unknown'];
+export declare function buildClaudeNamespace(ns: string): NamespaceDefinition;
+/** The canonical ordered list of type names registered by this namespace. */
+export declare const CLAUDE_TYPE_NAMES: readonly ['SessionLog', 'Decision', 'Todo', 'AgentRule', 'CouncilSession', 'CouncilAdvisor', 'Memory', 'AnchorIntent', 'Concept', 'ConceptLink', 'Skill', 'AgentIdentity', 'AgentMessage', 'HostInstall'];
+/**
+ * Architecture namespace — Claude-lineage code-review findings. Kept separate
+ * from the claude context namespace so lifecycle (compaction, retention,
+ * audit) differs: architectural findings outlive session-scoped rationale.
+ *
+ * Single type today (ArchitectureConcern). Notes:
+ *   - `archived` is `field.boolean()` to match every other type that carries
+ *     archived state.
+ *   - `supersedes` is a self-ref `field.crossRef` edge with `set_null` —
+ *     a concern survives the one it superseded going away.
+ */
+export declare function buildArchitectureNamespace(ns: string): NamespaceDefinition;
+export declare const ARCHITECTURE_TYPE_NAMES: readonly ['ArchitectureConcern'];

package/dist/nl-rulings.d.ts

@@ -0,0 +1,76 @@
+/**
+ * How people talk about cortext, for substrate's NL parser and judge. Curated
+ * operator rulings, kept here so the eval and production read one copy, owned
+ * by the namespace. Declared via `defineNamespace` annotations; substrate's NL
+ * layer validates them and the runtime can override per key.
+ */
+export declare const CORTEXT_NL_RULINGS: {
+    unscopedTypes: string[];
+    liveStatus: {
+        Todo: string;
+    };
+    timeField: {
+        SessionLog: string;
+    };
+    typeAliases: {
+        inbox: string;
+        mail: string;
+        agents: string;
+        agent: string;
+        session: string;
+        sessions: string;
+        anchor: string;
+        rule: string;
+        rules: string;
+        task: string;
+        tasks: string;
+        decide: string;
+        decided: string;
+    };
+    fieldAliases: {
+        repo: string;
+        repository: string;
+    };
+    valueAliases: {
+        'in force': {
+            type: string;
+            field: string;
+            eq: string;
+        }[];
+        'signal-gated': {
+            type: string;
+            field: string;
+            startsWith: string;
+        }[];
+        ship: {
+            type: string;
+            field: string;
+            eq: string;
+        }[];
+        shipped: {
+            type: string;
+            field: string;
+            eq: string;
+        }[];
+        drop: {
+            type: string;
+            field: string;
+            in: string[];
+        }[];
+        dropped: {
+            type: string;
+            field: string;
+            in: string[];
+        }[];
+    };
+    typeNotes: {
+        SessionLog: string;
+        Decision: string;
+        Todo: string;
+        Memory: string;
+        AgentMessage: string;
+        AgentIdentity: string;
+        Concept: string;
+        AgentRule: string;
+    };
+};

package/dist/onboard.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Onboard route — returns a static JSON body describing the claude namespace
+ * surface. Mounted at `/substrate/v1/plugins/cortext/onboard` (the router is already
+ * prefixed by the server's `createPluginRouter`).
+ *
+ * Endpoint paths in the body:
+ *   - Core query/mutate live at the unqualified `/substrate/v1/query` + `/substrate/v1/mutate`
+ *     (§4.7). The namespace now rides inside the frame key (`<ns>/<name>`),
+ *     not the URL.
+ *   - Compact moves under the plugin prefix (`/substrate/v1/plugins/cortext/compact`).
+ *   - WS endpoint still takes `namespace` as a companion field for agents
+ *     that pre-bake their frame-key prefix.
+ */
+import type { PluginRouteContext, PluginRouter } from '@mnmal-ai/substrate/sdk';
+export declare function registerOnboardRoute(router: PluginRouter, _ctx: PluginRouteContext, retention: number, namespace: string): void;

package/dist/participants.d.ts

@@ -0,0 +1,32 @@
+/**
+ * "Only the parties involved, or an operator" — the row-level authority the
+ * mailbox and the identity directory share.
+ *
+ * A Policy is synchronous and sees the caller, never the row, so it can say
+ * WHICH fields a write may touch but not WHOSE row it is. These wrappers sit
+ * on the resolver instead: they read the row, decide, and only then hand the
+ * call to the resolver they wrap. An id that matches no row falls through to
+ * the wrapped resolver, which owns the not-found contract.
+ *
+ * An operator is an identity granted `admin` (or `*`) in this namespace.
+ */
+import type { NamespaceInstallContext, RegistryEntryResolver, RequestContext } from '@mnmal-ai/substrate/sdk';
+/** Whether the caller holds `admin` (or `*`) in the namespace it is calling. */
+export declare function isOperator(ctx: RequestContext): boolean;
+/**
+ * AgentMessage update/delete: the sender, the recipient, or an operator.
+ * The sender is the key that signed the send (`_metadata.createdBy`); the
+ * recipient is the kid on the addressed directory row. Archiving someone
+ * else's mail hides it from their inbox, and deleting it destroys it, so
+ * neither is a bystander's call.
+ */
+export declare function messageParticipantsOnly(installCtx: NamespaceInstallContext, name: string, inner: RegistryEntryResolver): RegistryEntryResolver;
+/**
+ * AgentIdentity update: the identity itself (the caller's kid is the row's
+ * kid) or an operator. `kid` is the row's identity, so changing it is an
+ * operator act even on your own row: otherwise a row could be renamed onto a
+ * kid whose mail it would then receive.
+ */
+export declare function identitySelfOnly(installCtx: NamespaceInstallContext, name: string, inner: RegistryEntryResolver): RegistryEntryResolver;
+/** AgentIdentity delete: operators only. Mail hangs off these rows. */
+export declare function operatorOnly(name: string, inner: RegistryEntryResolver): RegistryEntryResolver;