@north-light/api 0.3.446 → 0.3.448

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.1";
+export declare const CONTRACT_LEVEL = "1.2";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -12,7 +12,7 @@
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export const CONTRACT_LEVEL = '1.1';
+export const CONTRACT_LEVEL = '1.2';
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export const REQUIRED_CONTRACT_HEADER = 'Crouter-Required-Contract';
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

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

@@ -210,6 +210,11 @@ export interface NodeFaultDTO {
 /** The full node view — summary ∪ identity extras ∪ edges ∪ paths. Returned by
  *  `GET /v1/nodes/{id}` and by the create/lifecycle actions that yield a node. */
 export interface NodeDetailDTO extends Omit<NodeSummaryDTO, 'outcome'> {
+    /** Set when another of your machines homes this node and answered: `{id, name}` of that machine. */
+    machine?: {
+        id: string;
+        name: string;
+    };
     outcome: NodeOutcomeDTO | null;
     /** Node that created this node, or null when an external process did. */
     creator: NodeIdDTO | null;

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

@@ -74,6 +74,8 @@ export interface OwnerReadData {
  *  structured fields (for the built-in kinds, the `*ReadData` shapes above). */
 export interface ObjectLiveReadDTO {
     state: 'object';
+    /** Set when another of your machines homes the object and answered: `{id, name}` of that machine. */
+    machine?: MachineRefDTO;
     type: string;
     object: ObjectDTO;
     text: string;
@@ -83,15 +85,28 @@ export interface ObjectLiveReadDTO {
 export interface ObjectDeletedDTO {
     state: 'deleted';
     deleted: ObjectDTO;
+    machine?: MachineRefDTO;
+}
+/** A machine of your account, as an answer names it. */
+export interface MachineRefDTO {
+    id: string;
+    name: string;
+}
+/** No machine answered for `ref`, and the ones that could not answer are listed: the object may be on one of them. Never a "missing". */
+export interface ObjectUnknownDTO {
+    state: 'unknown';
+    ref: string;
+    unreachable: string[];
 }
 /** The name's first segment is no handle on this runtime; the object may live on another runtime. */
 export interface ObjectRemoteDTO {
     state: 'remote';
     remote: string;
 }
-export type ObjectReadDTO = ObjectLiveReadDTO | ObjectDeletedDTO | ObjectRemoteDTO;
+export type ObjectReadDTO = ObjectLiveReadDTO | ObjectDeletedDTO | ObjectRemoteDTO | ObjectUnknownDTO;
 export interface ObjectReadQuery {
-    fields?: boolean;
+    fields?: boolean; /** Read on this machine (`runtime:<id>`), as a merged listing or inbox entry names it. */
+    machine?: string;
 }
 export interface ObjectListRequest {
     /** A kind name. */
@@ -105,15 +120,29 @@ export interface ObjectListRequest {
     deleted?: boolean;
     limit?: number;
     cursor?: string;
+    /** List only this machine (`runtime:<id>`), paging through its cursor. `self` lists only this machine without labels. */
+    machine?: string;
 }
 export interface ObjectListItemDTO extends ObjectDTO {
+    /** The machine of your account that homes the row; set on a merged or `--machine` listing. */
+    machine?: MachineRefDTO;
     summary?: string | null;
     /** A document's rule count. */
     rules?: number;
 }
+export type MachineListState = 'ok' | 'unreachable' | 'too_old';
+/** How one machine answered a merged listing; `more` says its first page was not all of it (page it with `--machine`). */
+export interface MachineListEntryDTO {
+    machine_id: string;
+    name: string;
+    state: MachineListState;
+    more: boolean;
+}
+/** `machines` is present when this runtime belongs to an account; `next_cursor` is always this machine's (or, with `machine`, that machine's). */
 export interface ObjectListDTO {
     items: ObjectListItemDTO[];
     next_cursor: string | null;
+    machines?: MachineListEntryDTO[];
 }
 export interface ObjectSearchRequest {
     text: string;
@@ -151,10 +180,12 @@ export interface UnwatchQuery {
 export interface WatchResultDTO {
     object: ObjectDTO;
     patterns: string[];
+    machine?: MachineRefDTO;
 }
 export interface UnwatchResultDTO {
     object: ObjectDTO;
     removed: number;
+    machine?: MachineRefDTO;
 }
 export type EdgeTypeName = 'acted-on' | 'links-to' | 'watches';
 export interface EdgesQuery {

package/dist/api/error-codes.d.ts

@@ -89,6 +89,11 @@ export declare const errorCodes: {
         readonly status: 403;
         readonly retryable: false;
     };
+    readonly app_not_granted: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
     readonly isolated_run: {
         readonly type: "permission_error";
         readonly status: 403;
@@ -114,6 +119,16 @@ export declare const errorCodes: {
         readonly status: 416;
         readonly retryable: false;
     };
+    readonly not_here: {
+        readonly type: "invalid_request_error";
+        readonly status: 404;
+        readonly retryable: false;
+    };
+    readonly peer_version_too_old: {
+        readonly type: "invalid_request_error";
+        readonly status: 426;
+        readonly retryable: false;
+    };
     readonly conflict: {
         readonly type: "invalid_request_error";
         readonly status: 409;

package/dist/api/error-codes.js

@@ -25,11 +25,17 @@ export const errorCodes = {
     question_pages_off: { type: 'permission_error', status: 403, retryable: false },
     // An unsandboxed machine (a computer joined to a Northlight account) runs only the person's own terminal agents; app grantees run on the hosted machine.
     unsandboxed_machine: { type: 'permission_error', status: 403, retryable: false },
+    // A forwarded app actor (an app node on another of the person's machines) whose app holds no active mirrored grant on this machine; refused before any row dispatch.
+    app_not_granted: { type: 'permission_error', status: 403, retryable: false },
     isolated_run: { type: 'permission_error', status: 403, retryable: false },
     provider_version_retired: { type: 'permission_error', status: 403, retryable: false },
     invalid_scope: { type: 'invalid_request_error', status: 400, retryable: false },
     invalid_request: { type: 'invalid_request_error', status: 400, retryable: false },
     range_not_satisfiable: { type: 'invalid_request_error', status: 416, retryable: false },
+    // A forwarded call landed on a machine that holds only a stub of the object; the caller asks the other machines again. Details `{ id, home_machine }`.
+    not_here: { type: 'invalid_request_error', status: 404, retryable: false },
+    // A peer machine runs a crtr release below the peer-protocol floor; details `{ peer_version, floor, receiver_version }`. Update it with `crtr sys update`.
+    peer_version_too_old: { type: 'invalid_request_error', status: 426, retryable: false },
     conflict: { type: 'invalid_request_error', status: 409, retryable: false },
     not_found: { type: 'invalid_request_error', status: 404, retryable: false },
     model_unavailable: { type: 'invalid_request_error', status: 404, retryable: false },

package/dist/core/scoped-state/settings.js

@@ -1,13 +1,31 @@
 import { prepared as cachedStatement } from '../sqlite-statements.js';
 import { createHash } from 'node:crypto';
 import { openScopedStore, withScopedWrite } from './db.js';
-function ensureOwner(db, owner) {
+/**
+ * The owner row ties a store to the thing it belongs to. For user and profile
+ * owners the recorded root is the guard: those rows share one store, and a row
+ * whose root differs belongs to something else. A project store is different —
+ * it lives inside the root that opens it (`<root>/operations.db`), so the
+ * location is the identity and the recorded root is only a note of where the
+ * directory last was. When the directory is moved or renamed the note goes
+ * stale; the owner is still the same project, so a write rebinds the note and a
+ * read accepts it. Kind and profile still have to match, so a user or profile
+ * store is never accepted as a project owner.
+ */
+function ensureOwner(db, owner, access) {
     const row = cachedStatement(db, 'SELECT kind, root, profile_id FROM scope_owners WHERE owner_key = ?').get(owner.key);
     if (!row)
         throw new Error(`scoped SQL owner is missing: ${owner.key}`);
-    if (row.kind !== owner.kind || row.root !== owner.root || (owner.profileId ?? null) !== row.profile_id) {
+    if (row.kind !== owner.kind || (owner.profileId ?? null) !== row.profile_id) {
         throw new Error(`scoped SQL owner does not match its root: ${owner.key}`);
     }
+    if (row.root === owner.root)
+        return;
+    if (owner.kind !== 'project' || owner.store.kind !== 'project' || owner.store.root !== owner.root) {
+        throw new Error(`scoped SQL owner does not match its root: ${owner.key}`);
+    }
+    if (access === 'write')
+        cachedStatement(db, 'UPDATE scope_owners SET root = ? WHERE owner_key = ?').run(owner.root, owner.key);
 }
 function revisionFor(row) {
     return row === undefined ? 'absent' : createHash('sha256').update(row.raw_json).digest('hex');
@@ -23,7 +41,7 @@ export class SettingsRevisionConflictError extends Error {
 }
 export function readRawSettingsWithRevision(owner) {
     const db = openScopedStore(owner.store);
-    ensureOwner(db, owner);
+    ensureOwner(db, owner, 'read');
     const row = readRawSettingsRow(db, owner);
     return { revision: revisionFor(row), settings: row === undefined ? null : JSON.parse(row.raw_json) };
 }
@@ -32,7 +50,7 @@ export function readRawSettings(owner) {
 }
 export function replaceRawSettings(owner, next, ifRevision, validate) {
     return withScopedWrite(owner.store, (db) => {
-        ensureOwner(db, owner);
+        ensureOwner(db, owner, 'write');
         const current = readRawSettingsRow(db, owner);
         if (ifRevision !== revisionFor(current))
             throw new SettingsRevisionConflictError();
@@ -46,13 +64,13 @@ export function replaceRawSettings(owner, next, ifRevision, validate) {
 }
 export function writeRawSettings(owner, raw) {
     withScopedWrite(owner.store, (db) => {
-        ensureOwner(db, owner);
+        ensureOwner(db, owner, 'write');
         cachedStatement(db, `INSERT INTO scope_settings(owner_key, raw_json) VALUES (?, ?) ON CONFLICT(owner_key) DO UPDATE SET raw_json=excluded.raw_json`).run(owner.key, JSON.stringify(raw));
     });
 }
 export function mutateRawSettings(owner, mutate) {
     return withScopedWrite(owner.store, (db) => {
-        ensureOwner(db, owner);
+        ensureOwner(db, owner, 'write');
         const row = cachedStatement(db, 'SELECT raw_json FROM scope_settings WHERE owner_key = ?').get(owner.key);
         const result = mutate(row ? JSON.parse(row.raw_json) : {});
         cachedStatement(db, `INSERT INTO scope_settings(owner_key, raw_json) VALUES (?, ?) ON CONFLICT(owner_key) DO UPDATE SET raw_json=excluded.raw_json`).run(owner.key, JSON.stringify(result.next));
@@ -61,7 +79,7 @@ export function mutateRawSettings(owner, mutate) {
 }
 export function readBookkeeping(owner) {
     const db = openScopedStore(owner.store);
-    ensureOwner(db, owner);
+    ensureOwner(db, owner, 'read');
     const bookkeeping = cachedStatement(db, 'SELECT last_self_check, active_canvas FROM scope_bookkeeping WHERE owner_key = ?').get(owner.key);
     const marketplaces = Object.fromEntries(cachedStatement(db, 'SELECT name, last_updated FROM scope_marketplaces WHERE owner_key = ?').all(owner.key).map((row) => [row.name, row.last_updated === null ? {} : { last_updated: row.last_updated }]));
     const plugins = Object.fromEntries(cachedStatement(db, 'SELECT name, last_updated, etag, checked_at FROM scope_plugins WHERE owner_key = ?').all(owner.key).map((row) => [row.name, { ...(row.last_updated === null ? {} : { last_updated: row.last_updated }), ...(row.etag === null ? {} : { etag: row.etag }), ...(row.checked_at === null ? {} : { checked_at: row.checked_at }) }]));
@@ -69,7 +87,7 @@ export function readBookkeeping(owner) {
 }
 export function writeBookkeeping(owner, state) {
     withScopedWrite(owner.store, (db) => {
-        ensureOwner(db, owner);
+        ensureOwner(db, owner, 'write');
         cachedStatement(db, `INSERT INTO scope_bookkeeping(owner_key, last_self_check, active_canvas) VALUES (?, ?, ?) ON CONFLICT(owner_key) DO UPDATE SET last_self_check=excluded.last_self_check, active_canvas=excluded.active_canvas`).run(owner.key, state.last_self_check ?? null, state.activeCanvas ?? null);
         cachedStatement(db, 'DELETE FROM scope_marketplaces WHERE owner_key = ?').run(owner.key);
         cachedStatement(db, 'DELETE FROM scope_plugins WHERE owner_key = ?').run(owner.key);

package/dist/shared/generated-context.d.ts

@@ -53,6 +53,8 @@ export interface InboxCardEntry {
 /** An already-resolved sender section supplied to the pure digest formatter. */
 export interface InboxCardSection {
     id: string;
+    /** The machine of the account the sender lives on, when it is not this one. */
+    machine?: string;
     entries: readonly InboxCardEntry[];
 }
 export interface GeneratedCard {
@@ -80,4 +82,10 @@ export declare function isHumanWordsEntry(entry: CardEntry): boolean;
 /** Explain how an inbox entry's ref is read without guessing its filesystem location. */
 export declare function formatInboxRefInstruction(ref: string): string;
 /** Format a complete inbox card from report bodies resolved by the caller. */
+/** The machine a section's sender lives on, when its entries say it is another one (`data.from_machine`, set by the home side of a forwarded send). */
+export declare function machineOfEntries(items: readonly {
+    data?: Record<string, unknown>;
+}[]): {
+    machine?: string;
+};
 export declare function formatInboxCard(sections: readonly InboxCardSection[]): string;

package/dist/shared/generated-context.js

@@ -221,6 +221,11 @@ export function formatInboxRefInstruction(ref) {
         : `Read this report with \`crtr canvas read ${ref}\`.`;
 }
 /** Format a complete inbox card from report bodies resolved by the caller. */
+/** The machine a section's sender lives on, when its entries say it is another one (`data.from_machine`, set by the home side of a forwarded send). */
+export function machineOfEntries(items) {
+    const machine = items.map((i) => i.data?.['from_machine']).find((m) => typeof m === 'string');
+    return machine === undefined ? {} : { machine };
+}
 export function formatInboxCard(sections) {
     const body = sections.map((section) => {
         const entries = section.entries.map((entry) => {
@@ -229,7 +234,7 @@ export function formatInboxCard(sections) {
                 : undefined;
             return `<entry${formatAttributes({ kind: entry.kind, ref: entry.ref, disposition })}>${escapeXmlText(entry.body)}</entry>`;
         }).join('\n');
-        return `<from${formatAttributes({ id: section.id })}>${entries}</from>`;
+        return `<from${formatAttributes({ id: section.id, machine: section.machine })}>${entries}</from>`;
     }).join('\n');
     return formatCard('inbox', {}, body);
 }

package/dist/shared/inbox-entry-body.js

@@ -42,7 +42,7 @@ function objectText(o) {
     if (o.type === 'job')
         return `job ${o.id} (\`${o.name}\`)`;
     if (o.type === 'node')
-        return `node ${o.name} (${o.id})`;
+        return `node ${o.name} (${o.id})${o.machine ? ` on ${o.machine}` : ''}`;
     return `${o.type} ${o.name}`;
 }
 function actorText(entry, push) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.446",
+  "version": "0.3.448",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",