@north-light/crouter-api 0.3.180 → 0.3.181

package/README.md

@@ -41,11 +41,18 @@ autostart hook.
   canvas, worktree, and human-in-the-loop.
 - **`routes` / `API_VERSION`** — pure path builders for the `/v1` surface.
 - **`ApiError` / `ErrorBody` / `isErrorBody`** — the error contract.
+- **`@north-light/crouter-api/doc-link-grammar`** — the `[[canonical/name]]`
+  memory-document link grammar (`findDocLinks`, `docLinkNames`,
+  `isDocLinkName`). Zero imports and browser-safe, so a UI can scan transcript
+  markdown for doc links in the renderer and hand each name to
+  `client.resolveMemoryDoc(name, nodeId)`. Import the subpath, not the root, in
+  a browser bundle — the root pulls `CrtrClient` and its Node built-ins.
 
 ## Source of truth & releases
 
 The source lives in the [`crouter`](https://github.com/vallum-security/crouter)
-repo at `src/api/`; this package is a build-and-publish mirror of that subtree
-(it carries no source of its own). It is published by the `publish-api.yml`
+repo at `src/api/`, plus `src/core/memory/doc-link-grammar.ts` for the subpath
+above; this package is a build-and-publish mirror of those files (it carries no
+source of its own). It is published by the `publish-api.yml`
 GitHub Action when a tag matching `api-vX.Y.Z` is pushed — the tag version must
 match this package's `version`.

package/dist/{client.d.ts → api/client.d.ts}

@@ -5,11 +5,12 @@ import type { PushReportRequest, PushReportResultDTO, ReportDTO, ReportsQuery }
 import type { CloseRequest, CloseResultDTO, PromoteRequest, RelaunchRootResultDTO, ReviveRequest, ReviveResultDTO, WaitRequest, YieldRequest } from './dto/lifecycle.js';
 import type { SubscribeRequest, SubscriptionDTO } from './dto/subscriptions.js';
 import type { FocusDTO, RegisterFocusRequest, SetFocusPaneRequest } from './dto/focus.js';
-import { type ArmCronRequest, type CancelCronQuery, type CronDTO, type CronRunDTO, type CronScopeQuery, type CronShowDTO, type ListCronsQuery } from './dto/crons.js';
+import { type ArmCronRequest, type CancelCronQuery, type CronDTO, type CronRunDTO, type CronScopeQuery, type CronShowDTO, type ListCronsQuery, type PokeCronsResult } from './dto/crons.js';
 import type { NodeConfigPatch } from './dto/config.js';
 import type { AttachEnsureRequest, AttachEnsureResultDTO } from './dto/attach.js';
 import type { EnsureProfileRequest, ProfileDTO } from './dto/profiles.js';
 import type { FilePeekDTO } from './dto/files.js';
+import type { MemoryDocRefDTO } from './dto/memory.js';
 import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredentialRequest, ModelAuthListDTO } from './dto/modelauth.js';
 import type { CreateHumanBridgeRequest, HumanBridgeResultDTO, HumanCancelRequest, HumanCancelResultDTO, HumanResolveRequest, HumanResolveResultDTO } from './dto/human.js';
 import type { CancelReviewRequest, CreateReviewRequest, ListReviewsQuery, ReviewCancelResultDTO, ReviewDocumentBaseDTO, ReviewDTO, ReviewListDTO, ReviewSubmitResultDTO } from './dto/reviews.js';
@@ -131,6 +132,10 @@ export declare class CrtrClient {
     runCron(cronId: string, q?: CronScopeQuery): Promise<CronRunDTO>;
     /** Cancel one cron (`DELETE /v1/crons/:cronId`, idempotent). */
     cancelCron(cronId: string, q?: CancelCronQuery): Promise<void>;
+    /** Bare eligibility poke (`POST /v1/crons/poke`): re-dues every held active
+     *  cron now — "something changed; re-check now". Canvas-wide, label-free,
+     *  idempotent, and free when nothing is held. */
+    pokeCrons(): Promise<PokeCronsResult>;
     ensureAttach(id: string, req?: AttachEnsureRequest): Promise<AttachEnsureResultDTO>;
     getReports(id: string, q?: ReportsQuery): Promise<ReportDTO[]>;
     getTranscript(id: string, q?: TranscriptQuery): Promise<TranscriptDTO>;
@@ -143,6 +148,10 @@ export declare class CrtrClient {
     /** Read an absolute host path as UTF-8 (capped, `truncated` when clipped) for
      *  the browser file-peek panel. */
     peekFile(path: string): Promise<FilePeekDTO>;
+    /** Resolve a `[[name]]` memory-document link to the absolute path the given
+     *  node would read — the node's own precedence chain, not this process's.
+     *  Pair with `peekFile` to render the document. */
+    resolveMemoryDoc(name: string, nodeId: string): Promise<MemoryDocRefDTO>;
     ensureProfile(name: string, req?: EnsureProfileRequest): Promise<ProfileDTO>;
     listProfiles(): Promise<ProfileDTO[]>;
     getProfile(name: string): Promise<ProfileDTO>;

package/dist/{client.js → api/client.js}

@@ -227,6 +227,12 @@ export class CrtrClient {
     async cancelCron(cronId, q) {
         await this.request('DELETE', withQuery(routes.cron(this.cronPath(cronId)), q));
     }
+    /** Bare eligibility poke (`POST /v1/crons/poke`): re-dues every held active
+     *  cron now — "something changed; re-check now". Canvas-wide, label-free,
+     *  idempotent, and free when nothing is held. */
+    pokeCrons() {
+        return this.request('POST', routes.cronsPoke(), {});
+    }
     ensureAttach(id, req) {
         return this.request('POST', routes.nodeAttach(this.nodePath(id)), req ?? {});
     }
@@ -257,6 +263,13 @@ export class CrtrClient {
     peekFile(path) {
         return this.request('GET', withQuery(routes.filePeek(), { path }));
     }
+    // ---- Memory documents --------------------------------------------------
+    /** Resolve a `[[name]]` memory-document link to the absolute path the given
+     *  node would read — the node's own precedence chain, not this process's.
+     *  Pair with `peekFile` to render the document. */
+    resolveMemoryDoc(name, nodeId) {
+        return this.request('GET', withQuery(routes.memoryResolve(), { name, node: nodeId }));
+    }
     // ---- Profiles ----------------------------------------------------------
     ensureProfile(name, req) {
         return this.request('PUT', routes.profile(name), req ?? {});

package/dist/{dto → api/dto}/broker.d.ts

@@ -28,6 +28,38 @@ export interface BrokerWelcomeSnapshot<M = unknown> {
 export interface BrokerWelcomeFrame<M = unknown> {
     type: 'welcome';
     snapshot?: BrokerWelcomeSnapshot<M>;
+    /** The last few id-bearing user-message dispatches from the broker's message
+     *  ledger, oldest first — so a reattaching follower can key the snapshot's
+     *  trailing user wakes by id (the id a sender minted via `message_id` on
+     *  `POST .../messages`) instead of discarding them heuristically. Live-process
+     *  memory only: a broker restart loses it. Absent on a broker pinned to an
+     *  older runtime generation. */
+    recentUserMessages?: Array<{
+        id: string;
+        text: string;
+    }>;
+}
+/**
+ * The additive identity fields the broker sets on a relayed pi `queue_update`:
+ * id arrays PARALLEL to pi's text arrays (`steeringIds[i]` identifies
+ * `steering[i]`). Sender-minted when the send carried `message_id`,
+ * broker-minted otherwise. Absent on a broker pinned to an older runtime
+ * generation — consumers fall back to bare texts. Intersect with the pinned pi
+ * `queue_update` event shape to read them typed.
+ */
+export interface RelayedQueueUpdateIdentity {
+    steeringIds?: string[];
+    followUpIds?: string[];
+}
+/**
+ * The additive identity field the broker sets on a relayed USER-role
+ * `message_start`: the message's crouter id — the `message_id` its sender
+ * minted, or a broker-minted one. Absent when the message carries none (an
+ * engine-command expansion, a pre-ledger replay, an older broker). Intersect
+ * with the pinned pi `message_start` event shape to read it typed.
+ */
+export interface RelayedUserMessageStartIdentity {
+    crtrMessageId?: string;
 }
 /**
  * The broker-control frames a relay consumer reads: `welcome` (catch-up snapshot)

package/dist/{dto → api/dto}/crons.d.ts

@@ -53,6 +53,14 @@ export interface CronDTO {
     sink: string | null;
     tier: string;
     state: CronStateDTO;
+    /** True while the row is parked by the exit-75 owed-gate disposition: the
+     *  last scheduled run declared "owed but not currently eligible", so the
+     *  occurrence was not spent. A daemon poke re-dues it now; otherwise a
+     *  recurring row re-checks at its natural `fire_at` slot (the backstop) and
+     *  a held one-shot waits for a poke until `expires_at` deletes it. `state`
+     *  stays honest (active|paused) — renderers derive; an active held row must
+     *  never present as paused. */
+    held: boolean;
     run_state: CronRunStateDTO;
     /** Recent health: the most recent settled run, or null if it never ran. */
     last_run: CronLastRunDTO | null;
@@ -93,6 +101,15 @@ export interface CronRunDTO {
     /** What the sink did with this run's output, or why it didn't. */
     delivered: string | null;
 }
+/** `POST /v1/crons/poke` — the bare daemon-level eligibility poke. Re-dues
+ *  every held active cron now; paused rows keep their held state. Idempotent
+ *  and free when nothing is held. */
+export interface PokeCronsResult {
+    /** How many held rows were re-dued — for the caller's log line. */
+    unparked: number;
+    /** The poke receipt instant (UTC). */
+    at: IsoTime;
+}
 /** `GET /v1/crons/:cronId` — one cron with its run-log ring (most recent first). */
 export interface CronShowDTO {
     cron: CronDTO;

package/dist/api/dto/memory.d.ts

@@ -0,0 +1,17 @@
+/** `GET /v1/memory/resolve?name=<name>&node=<id>` result — where the named
+ *  document lives for that node. Resolution runs the node's own precedence
+ *  chain (its context store, its project stack, its profile, user, builtin), so
+ *  the same name can answer with different documents for different nodes. */
+export interface MemoryDocRefDTO {
+    /** The document's canonical identity (its frontmatter `name`, else its
+     *  path-derived name) — which may differ from the queried name when the query
+     *  was a bare leaf or a directory whose INDEX resolved. */
+    name: string;
+    /** Which store it came from: node | project | profile | user | builtin. */
+    scope: string;
+    /** Absolute path to the `.md` file. */
+    path: string;
+    /** The owning plugin's name when the doc is mounted from an installed plugin,
+     *  absent for a native scope doc. */
+    plugin?: string;
+}

package/dist/api/dto/memory.js

@@ -0,0 +1,6 @@
+// Memory-document resolution DTO. Backs `GET /v1/memory/resolve` — a client
+// holding a `[[name]]` link out of a node's transcript turns it into the
+// absolute path of the document that node would read, then peeks that path.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export {};

package/dist/{dto → api/dto}/messages.d.ts

@@ -26,6 +26,11 @@ export interface SendMessageRequest {
      *  body only — rejected with fresh/reopen/situational_context/
      *  output_schema or tier 'deferred'. Absent → durable inbox (unchanged). */
     delivery?: 'interactive';
+    /** Sender-minted message identity for a `delivery:'interactive'` send. The
+     *  broker mirrors it through pi's queues and echoes it on the relayed user
+     *  `message_start` (`crtrMessageId`), so an optimistic sender (the gateway)
+     *  retires its pending entry by exact id. Ignored on the durable-inbox path. */
+    message_id?: string;
 }
 /** Result of an immediate message send. */
 export interface MessageResultDTO {

package/dist/{dto → api/dto}/reviews.d.ts

@@ -38,6 +38,9 @@ export interface ReviewDTO {
     created: IsoTime;
     /** Daemon open timestamp, after the companion binds. */
     opened_at?: IsoTime;
+    /** When the human submitted a review whose companion was still working. The
+     *  review remains `open` until the companion goes quiet. */
+    submit_requested_at?: IsoTime;
     /** Daemon source-read status at projection time. */
     source_missing: boolean;
     /** Daemon-owned current comment-coordinate source digest. */
@@ -73,12 +76,13 @@ export interface ListReviewsQuery {
 export interface ReviewListDTO {
     reviews: ReviewDTO[];
 }
-/** Daemon-derived result of terminal review approval. */
+/** Daemon-derived result of review approval, which may still be waiting on the
+ *  review's companion. */
 export interface ReviewSubmitResultDTO {
     review: ReviewDTO;
-    /** Immutable approval result. */
-    result: FeedbackResultDTO;
-    outcome: 'settled' | 'already_settled';
+    /** Immutable approval result; absent while the approval awaits the companion. */
+    result?: FeedbackResultDTO;
+    outcome: 'settled' | 'already_settled' | 'awaiting_companion';
 }
 /** Daemon-derived result of terminal review cancellation. */
 export interface ReviewCancelResultDTO {

package/dist/{index.d.ts → api/index.d.ts}

@@ -21,6 +21,7 @@ export * from './dto/canvas.js';
 export * from './dto/worktree.js';
 export * from './dto/human.js';
 export * from './dto/files.js';
+export * from './dto/memory.js';
 export * from './dto/inbox.js';
 export * from './dto/reviews.js';
 export * from './dto/review-comments.js';

package/dist/{index.js → api/index.js}

@@ -22,6 +22,7 @@ export * from './dto/canvas.js';
 export * from './dto/worktree.js';
 export * from './dto/human.js';
 export * from './dto/files.js';
+export * from './dto/memory.js';
 export * from './dto/inbox.js';
 export * from './dto/reviews.js';
 export * from './dto/review-comments.js';

package/dist/{routes.d.ts → api/routes.d.ts}

@@ -46,6 +46,7 @@ export declare const routes: {
     readonly cronPause: (cronId: string) => string;
     readonly cronResume: (cronId: string) => string;
     readonly cronRun: (cronId: string) => string;
+    readonly cronsPoke: () => string;
     readonly canvasAttention: () => string;
     readonly canvasAttentionCounts: () => string;
     readonly canvasHistorySearch: () => string;
@@ -81,4 +82,5 @@ export declare const routes: {
     readonly modelAuths: () => string;
     readonly modelAuth: (provider: string) => string;
     readonly filePeek: () => string;
+    readonly memoryResolve: () => string;
 };

package/dist/{routes.js → api/routes.js}

@@ -67,6 +67,7 @@ export const routes = {
     cronPause: (cronId) => `${V}/crons/${cronId}/pause`,
     cronResume: (cronId) => `${V}/crons/${cronId}/resume`,
     cronRun: (cronId) => `${V}/crons/${cronId}/run`,
+    cronsPoke: () => `${V}/crons/poke`,
     // Canvas maintenance / reads
     canvasAttention: () => `${V}/canvas/attention`,
     canvasAttentionCounts: () => `${V}/canvas/attention/counts`,
@@ -112,4 +113,7 @@ export const routes = {
     // Host file read (browser file-peek panel). The absolute path rides as a
     // `path` query param, not a path segment — it is not a single safe segment.
     filePeek: () => `${V}/files/peek`,
+    // Memory-document resolution (a `[[name]]` link in a node's transcript). Both
+    // the name and the node it is resolved for ride as query params.
+    memoryResolve: () => `${V}/memory/resolve`,
 };

package/dist/core/memory/doc-link-grammar.d.ts

@@ -0,0 +1,20 @@
+/** One `[[name]]` link occurrence found in a document body. */
+export interface DocLink {
+    /** Character index of the first `[` of `[[`. */
+    start: number;
+    /** Character index just past the closing `]]`. */
+    end: number;
+    /** The canonical document name between the brackets. */
+    name: string;
+}
+/** Is `name` a well-formed canonical doc-link name? */
+export declare function isDocLinkName(name: string): boolean;
+/**
+ * Find every `[[name]]` doc link in a markdown body, in order of appearance,
+ * skipping fenced code blocks and inline code spans (a link mentioned inside
+ * code is an example, not a reference). Occurrences are NOT deduplicated —
+ * callers collapse as needed.
+ */
+export declare function findDocLinks(body: string): DocLink[];
+/** The distinct link names in a body, first-appearance order. */
+export declare function docLinkNames(body: string): string[];

package/dist/core/memory/doc-link-grammar.js

@@ -0,0 +1,113 @@
+// doc-link-grammar.ts — the single source of truth for the `[[canonical/name]]`
+// memory-document link grammar. Zero imports, pure string ops, browser-safe —
+// any surface that highlights, resolves, or lints doc links imports THIS module
+// rather than re-implementing the bracket scan or the name shape. It ships to
+// external consumers as `@north-light/crouter-api/doc-link-grammar`, so a
+// browser UI rendering a node's transcript scans with the same grammar crtrd
+// validates `/v1/memory/resolve` names with.
+//
+// A doc link is a durable cross-reference written INSIDE a memory document's
+// body, pointing at another memory document by its exact canonical name (the
+// same identifier `crtr memory read <name>` takes; a directory INDEX is linked
+// by its folded bare-directory name). It is distinct from the interactive
+// `/name` inline-reference grammar (`inline-ref-grammar.ts`), which scans a
+// human's live composer text — links live in stored markdown and survive there.
+//
+// Links are POINTERS, never transclusion: nothing in the runtime auto-loads a
+// linked body into context. `crtr memory lint` fails a link that resolves to no
+// document; `crtr memory read` surfaces the resolved links of the doc it loads.
+//
+// This module never resolves anything: `findDocLinks` returns candidate links;
+// a caller decides a link is live by testing `name` against the corpus of
+// resolvable canonical names.
+// A canonical doc name: one or more `[A-Za-z0-9_-]+` segments joined by `/`.
+// Anything else between `[[` `]]` (spaces, `|` aliases, empty segments) is NOT
+// a doc link — the grammar has no alias/label form, by design.
+const NAME_RE = /^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/;
+const LINK_RE = /\[\[([^\[\]\n]+)\]\]/g;
+/** Is `name` a well-formed canonical doc-link name? */
+export function isDocLinkName(name) {
+    return NAME_RE.test(name);
+}
+/**
+ * Find every `[[name]]` doc link in a markdown body, in order of appearance,
+ * skipping fenced code blocks and inline code spans (a link mentioned inside
+ * code is an example, not a reference). Occurrences are NOT deduplicated —
+ * callers collapse as needed.
+ */
+export function findDocLinks(body) {
+    const links = [];
+    for (const segment of proseSegments(body)) {
+        LINK_RE.lastIndex = 0;
+        let m;
+        while ((m = LINK_RE.exec(segment.text)) !== null) {
+            const name = m[1];
+            if (!isDocLinkName(name))
+                continue;
+            links.push({ start: segment.offset + m.index, end: segment.offset + m.index + m[0].length, name });
+        }
+    }
+    return links;
+}
+/** The distinct link names in a body, first-appearance order. */
+export function docLinkNames(body) {
+    const seen = new Set();
+    const out = [];
+    for (const link of findDocLinks(body)) {
+        if (seen.has(link.name))
+            continue;
+        seen.add(link.name);
+        out.push(link.name);
+    }
+    return out;
+}
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+function* proseSegments(body) {
+    let offset = 0;
+    let fence = null; // the opening fence marker while inside a block
+    for (const line of body.split('\n')) {
+        const lineLen = line.length + 1; // + '\n' (harmless overcount on last line)
+        const fenceMatch = line.match(FENCE_RE);
+        if (fence !== null) {
+            // Inside a fenced block: only a closing fence of the same char and at
+            // least the same length ends it. Nothing in here is prose.
+            if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length) {
+                fence = null;
+            }
+            offset += lineLen;
+            continue;
+        }
+        if (fenceMatch) {
+            fence = fenceMatch[1];
+            offset += lineLen;
+            continue;
+        }
+        // Prose line: split around inline code spans (single-backtick pairs).
+        yield* proseParts(line, offset);
+        offset += lineLen;
+    }
+}
+function* proseParts(line, offset) {
+    let i = 0;
+    while (i < line.length) {
+        const open = line.indexOf('`', i);
+        if (open === -1) {
+            yield { offset: offset + i, text: line.slice(i) };
+            return;
+        }
+        // Backtick run: an inline span is delimited by runs of equal length.
+        let runEnd = open;
+        while (runEnd < line.length && line[runEnd] === '`')
+            runEnd++;
+        const run = line.slice(open, runEnd);
+        const close = line.indexOf(run, runEnd);
+        if (close === -1) {
+            // Unbalanced backticks: treat the rest as prose past the run.
+            yield { offset: offset + i, text: line.slice(i, open) };
+            i = runEnd;
+            continue;
+        }
+        yield { offset: offset + i, text: line.slice(i, open) };
+        i = close + run.length;
+    }
+}

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.180",
+  "version": "0.3.181",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, and the CrtrClient. Zero runtime dependencies.",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/api/index.js",
+  "types": "./dist/api/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "default": "./dist/index.js"
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/api/index.js",
+      "require": "./dist/api/index.js",
+      "default": "./dist/api/index.js"
+    },
+    "./doc-link-grammar": {
+      "types": "./dist/core/memory/doc-link-grammar.d.ts",
+      "import": "./dist/core/memory/doc-link-grammar.js",
+      "require": "./dist/core/memory/doc-link-grammar.js",
+      "default": "./dist/core/memory/doc-link-grammar.js"
     }
   },
   "files": [