@north-light/api 0.3.458 → 0.3.460

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.4";
+export declare const CONTRACT_LEVEL = "1.5";
 /** 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.4';
+export const CONTRACT_LEVEL = '1.5';
 /** 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/profiles.d.ts

@@ -112,6 +112,8 @@ export interface ProfileDTO {
     created_at: string;
     /** ISO timestamp of the most recent selection, or null if never selected. */
     last_used_at: string | null;
-    /** Absolute path of the profile's directory under its app's space (the legacy location of its pre-canvas markdown; the profile's documents live in the canvas). */
+    /** Absolute path of the profile's directory, `<app space>/profiles/<id>`: its settings root. The profile's documents live in the canvas, not here. */
+    profile_path: string;
+    /** @deprecated The same path as `profile_path`; kept for clients written before it existed. Removed in the next breaking release. */
     memory_path: string;
 }

package/dist/core/config.js

@@ -9,7 +9,7 @@ import { emitEvent } from './events/emit.js';
 import { atomicWriteJson, readJsonIfExists, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots, userScopeRoot } from './scope.js';
 import { listInstalledPluginsInRoot } from './installed-plugins.js';
-import { profileMemoryDir, listProfiles } from './profiles/manifest.js';
+import { profileDir, listProfiles } from './profiles/manifest.js';
 import { canonicalRoot, projectStore, userStore } from './scoped-state/paths.js';
 import { convertLegacyScopedStore, initializeFreshScopedStore } from './scoped-state/migrate.js';
 import { mutateRawSettings, readBookkeeping, readRawSettings, readRawSettingsWithRevision, replaceRawSettings, writeBookkeeping, writeRawSettings } from './scoped-state/settings.js';
@@ -47,7 +47,7 @@ function settingsOwnerForRoot(root) {
         return { store: projectStore(canonical), key: 'project', kind: 'project', root: canonical };
     }
     for (const profile of listProfiles()) {
-        const profilePath = canonicalRoot(profileMemoryDir(profile.profileId));
+        const profilePath = canonicalRoot(profileDir(profile.profileId));
         if (canonical === profilePath)
             return { store: userStore(userRoot), key: `profile:${profile.profileId}`, kind: 'profile', root: profilePath, profileId: profile.profileId };
     }
@@ -129,7 +129,7 @@ function rawSettingsOwnerForTarget(target) {
     if (!listProfiles().some((profile) => profile.profileId === target.profileId)) {
         throw notFound(`profile not found: ${target.profileId}`, { received: target.profileId, next: 'Run `crtr profile list` to see available profiles.' });
     }
-    return settingsOwnerForRoot(profileMemoryDir(target.profileId));
+    return settingsOwnerForRoot(profileDir(target.profileId));
 }
 export function readRawSettingsForTarget(target) {
     return readRawSettingsWithRevision(rawSettingsOwnerForTarget(target));
@@ -877,7 +877,7 @@ function readRawProfileConfig(profileId) {
     if (profileId === null || profileId === '')
         return null;
     try {
-        return readRawAtRoot(profileMemoryDir(profileId));
+        return readRawAtRoot(profileDir(profileId));
     }
     catch {
         return null;

package/dist/core/io.d.ts

@@ -59,6 +59,9 @@ interface ErrorPayloadBase {
     http_status?: number;
     /** Seconds the provider asked the caller to wait before retrying (a rate limit). */
     retry_after_s?: number;
+    /** The structured details the runtime attached to a refusal the caller must act on (a `machine_required`
+     *  answer's `candidates`). Rendered below the message and kept in `--json`. */
+    details?: Record<string, unknown>;
     next: string;
 }
 export type ErrorPayload = ErrorPayloadBase & ({
@@ -116,9 +119,16 @@ export declare function diag(message: string): void;
  *      under the daemon's coarse `provider_*` code and the provider's HTTP
  *      status. The provider's code, `next`, `field` and `Retry-After` reach the
  *      caller unchanged; the status→code map would flatten them to `conflict`.
- *   4. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *   4. A refusal the runtime itself rendered for `provider.call` (`options.providerCall`):
+ *      its envelope code came from the runtime's own table (`machine_required`,
+ *      `device_offline`, …), not from the HTTP status, so it is kept together with
+ *      its `details`. The caller of `provider.call` is the only one who knows the
+ *      envelope is that endpoint's, which is why this is an option and not inferred.
+ *   5. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
  *      and a caller-supplied-or-default `next`. */
-export declare function apiErrorToCliError(err: ApiError, next?: string): CrtrError;
+export declare function apiErrorToCliError(err: ApiError, next?: string, options?: {
+    providerCall?: boolean;
+}): CrtrError;
 /** Terminal error handler. Command-level failures (bad input, not-found,
  *  ambiguous) surface as the JSON response on stdout so the caller parses one
  *  contract. A daemon `ApiError` is translated to that same clean contract

package/dist/core/io.js

@@ -190,6 +190,9 @@ export function diag(message) {
     process.stderr.write(message + '\n');
 }
 // errors
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
 function payloadOf(e) {
     if (e instanceof InputError)
         return e.payload;
@@ -210,6 +213,7 @@ function payloadOf(e) {
         field: d.field,
         ...(typeof d.http_status === 'number' ? { http_status: d.http_status } : {}),
         ...(typeof d.retry_after_s === 'number' ? { retry_after_s: d.retry_after_s } : {}),
+        ...(isRecord(d.details) ? { details: d.details } : {}),
     };
     return result === undefined
         ? { ...base, next }
@@ -280,9 +284,14 @@ const STATUS_TO_CLI_CODE = {
  *      under the daemon's coarse `provider_*` code and the provider's HTTP
  *      status. The provider's code, `next`, `field` and `Retry-After` reach the
  *      caller unchanged; the status→code map would flatten them to `conflict`.
- *   4. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *   4. A refusal the runtime itself rendered for `provider.call` (`options.providerCall`):
+ *      its envelope code came from the runtime's own table (`machine_required`,
+ *      `device_offline`, …), not from the HTTP status, so it is kept together with
+ *      its `details`. The caller of `provider.call` is the only one who knows the
+ *      envelope is that endpoint's, which is why this is an option and not inferred.
+ *   5. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
  *      and a caller-supplied-or-default `next`. */
-export function apiErrorToCliError(err, next) {
+export function apiErrorToCliError(err, next, options = {}) {
     // A handover is NOT a down daemon: the successor is already up (the client
     // waited for its /healthz), so telling anyone to start one is wrong — the
     // only thing left is to re-issue the call.
@@ -304,12 +313,15 @@ export function apiErrorToCliError(err, next) {
     // A responding daemon can relay an unavailable provider or storage service.
     // HTTP 503 alone does not mean that crtrd is down.
     const d = err.details;
-    const provider = providerSupplied(err, d);
-    if (err.status === 503) {
+    const provider = providerSupplied(err, d, options.providerCall === true);
+    // A `device_timeout` the runtime rendered for `provider.call` (504) is the same operational class as a 503.
+    if (err.status === 503 || (options.providerCall === true && err.status === 504 && provider.code !== undefined)) {
         const code = provider.code ?? err.code;
         const details = {
             next: provider.next ?? next ?? 'Retry the command; if it persists, inspect the unavailable service named in the error.',
         };
+        if (provider.details !== undefined)
+            details['details'] = provider.details;
         if (provider.code !== undefined) {
             if (provider.field !== undefined)
                 details['field'] = provider.field;
@@ -333,6 +345,7 @@ export function apiErrorToCliError(err, next) {
             ...(provider.field !== undefined ? { field: provider.field } : {}),
             ...(provider.received !== undefined ? { received: provider.received } : {}),
             ...(provider.retryAfterS !== undefined ? { retry_after_s: provider.retryAfterS } : {}),
+            ...(provider.details !== undefined ? { details: provider.details } : {}),
             message: violations.length > 0 ? `${err.message}: ${violations.join('; ')}` : err.message.trim() !== '' ? err.message : `request refused (HTTP ${err.status}, ${err.code}) with no message`,
             next: provider.next ??
                 next ??
@@ -357,13 +370,32 @@ export function apiErrorToCliError(err, next) {
  *  did not originate at a provider, so non-provider status→code mapping is
  *  untouched. A code that is not a snake_case identifier, or that came with no
  *  provider HTTP status, is ignored. */
-function providerSupplied(err, d) {
+function providerSupplied(err, d, providerCall) {
+    const snake = (code) => typeof code === 'string' && /^[a-z][a-z0-9_]*$/.test(code);
+    // `provider.call` renders every refusal as a runtime envelope (`origin` set) whose `code` the runtime chose from its own
+    // table, so the code stands and `details` is the runtime's structured answer (not a provider's body). A code-less
+    // transport failure the client synthesized has no envelope and stays on the status map.
+    if (providerCall && err.origin !== undefined && err.origin !== 'provider' && snake(err.code)) {
+        const out = { code: err.code };
+        if (err.status === 503 || err.status === 504) {
+            out.next = err.retryable === true
+                ? 'Retry the command; if it persists, the machine or service named in the error is unavailable.'
+                : 'Read the error before retrying: the action may already have run.';
+        }
+        if (isRecord(err.details))
+            out.details = err.details;
+        if (err.param !== undefined)
+            out.field = err.param;
+        if (typeof err.retryAfterS === 'number')
+            out.retryAfterS = err.retryAfterS;
+        return out;
+    }
     if (err.origin !== 'provider' || d === undefined || d === null || typeof d !== 'object')
         return {};
     const out = {};
     // `details.status` is the provider's own HTTP status; the runtime's transport
     // diagnostics (`{status: null, code: 'timeout'}`) are not a provider's code.
-    if (typeof d.status === 'number' && typeof d.code === 'string' && /^[a-z][a-z0-9_]*$/.test(d.code))
+    if (typeof d.status === 'number' && snake(d.code))
         out.code = d.code;
     if (typeof d.next === 'string' && d.next.trim() !== '')
         out.next = d.next;

package/dist/core/layout.d.ts

@@ -6,7 +6,7 @@ export declare function userRoot(): string;
 export declare function appsRoot(): string;
 export declare function secretsDir(): string;
 export declare function profileSpace(app: string, id: string): {
-    memory: string;
+    dir: string;
     env: string;
     home: string;
 };
@@ -15,7 +15,7 @@ export declare function layoutVersionFile(): string;
 export declare function userFilesRoot(): string;
 export declare function appSpace(app: string): {
     root: string;
-    memory: string;
+    profiles: string;
     conversations: string;
     nodes: string;
     files: string;

package/dist/core/layout.js

@@ -44,7 +44,7 @@ export function profileSpace(app, id) {
         throw new Error(`invalid profile id: ${id}`);
     const space = appSpace(app);
     return {
-        memory: join(space.memory, 'profiles', id),
+        dir: join(space.profiles, id),
         env: join(secretsDir(), 'env', basename(space.root), id),
         home: space.home,
     };
@@ -62,7 +62,7 @@ export function appSpace(app) {
     if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(id) || id === '.' || id === '..')
         throw new Error(`invalid app id: ${app}`);
     const root = join(appsRoot(), id);
-    return { root, memory: join(root, 'memory'), conversations: join(root, 'conversations'), nodes: join(root, 'nodes'), files: join(root, 'files'), home: join(root, 'home'), cache: join(root, 'cache') };
+    return { root, profiles: join(root, 'profiles'), conversations: join(root, 'conversations'), nodes: join(root, 'nodes'), files: join(root, 'files'), home: join(root, 'home'), cache: join(root, 'cache') };
 }
 /** The folder an isolated cron runs in: `<app space>/crons/<cron_id>/`. It belongs to the cron, not to the node that armed it. */
 export function cronFolder(app, cronId) {

package/dist/core/profiles/manifest.d.ts

@@ -1,7 +1,7 @@
 import type { ProfileManifest } from '../../types.js';
 import type { DeliveryLimits, ProfileProject, ProfileProjectMemory } from '../../api/dto/profiles.js';
 export declare const ROOT_PROFILE_ID = "root-00000000";
-export declare function profileMemoryDir(profileId: string): string;
+export declare function profileDir(profileId: string): string;
 export declare function assertProfileProjects(entries: unknown): asserts entries is ProfileProject[];
 export declare function assertDeliveryLimits(value: unknown): asserts value is DeliveryLimits;
 export interface ProfileEntry {

package/dist/core/profiles/manifest.js

@@ -21,7 +21,7 @@ export const ROOT_PROFILE_ID = 'root-00000000';
 const ROOT_PROFILE_NAME = 'root';
 function profileApp(manifest) { return manifest.grantee ?? 'app:terminal'; }
 function scaffoldProfile(profileId, manifest) {
-    ensureDir(profileSpace(profileApp(manifest), profileId).memory);
+    ensureDir(profileSpace(profileApp(manifest), profileId).dir);
 }
 function assertSafeProfileId(profileId) {
     if (!ID_SHAPE.test(profileId)) {
@@ -31,12 +31,12 @@ function assertSafeProfileId(profileId) {
         });
     }
 }
-export function profileMemoryDir(profileId) {
+export function profileDir(profileId) {
     assertSafeProfileId(profileId);
     const stored = getStoredProfile(userScopeRoot(), profileId);
     if (stored === null)
         throw notFound(`profile not found: ${profileId}`, { received: profileId });
-    return profileSpace(profileApp(stored.manifest), profileId).memory;
+    return profileSpace(profileApp(stored.manifest), profileId).dir;
 }
 // Profile operands resolve against the scoped-state rows.
 export function assertProfileProjects(entries) {
@@ -523,7 +523,7 @@ export function deleteProfile(profileId) {
         const space = profileSpace(profileApp(loadExactProfileManifest(profileId).manifest), profileId);
         if (!deleteStoredProfile(userScopeRoot(), profileId))
             throw notFound(`profile not found: ${profileId}`, { received: profileId });
-        rmSync(space.memory, { recursive: true, force: true });
+        rmSync(space.dir, { recursive: true, force: true });
         rmSync(space.env, { force: true });
     });
 }

package/dist/core/render.d.ts

@@ -5,7 +5,7 @@ import type { ErrorPayload } from './io.js';
  *  after. Scalars (and nested objects) list as `- name: value` bullets, prose
  *  fields render as paragraphs, and arrays become a count lead-in plus a table
  *  or bullets. No root tag — the result is read as a continuation of the prompt. */
-export declare function renderResult(result: Record<string, unknown>, help: LeafHelp): string;
+export declare function renderResult(result: Record<string, unknown>, help: Pick<LeafHelp, 'output'>): string;
 /** Render a structured failure as an instruction-shaped block: what broke, what
  *  was received, and the recovery road sign — the same recovery info the JSON
  *  payload carries, shaped for the model to act on. */

package/dist/core/render.js

@@ -131,6 +131,10 @@ export function renderError(p) {
         lines.push(`http status: ${p.http_status}`);
     if (p.retry_after_s !== undefined)
         lines.push(`retry after: ${p.retry_after_s}s`);
+    // The runtime's structured answer (`machine_required`'s candidates): the caller acts on these values, so they are
+    // listed in full, arrays as a table.
+    if (p.details !== undefined && Object.keys(p.details).length > 0)
+        lines.push(renderResult(p.details, { output: [] }));
     if ('primaryCompleted' in p && p.primaryCompleted === true) {
         lines.push('primaryCompleted: true');
         lines.push(`Primary result (the command already completed):\n${fencedJson(p.result)}`);

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

@@ -164,7 +164,7 @@ function importUser(db, root) {
             if (!manifest || typeof manifest !== 'object' || !Array.isArray(manifest.projects) || typeof manifest.name !== 'string' || typeof manifest.created_at !== 'string')
                 throw new Error(`legacy profile manifest is malformed: ${path}`);
             cachedStatement(db, 'INSERT INTO profiles(id,name,created_at,last_used_at,paused_at,default_kind,grantee,metadata_json) VALUES(?,?,?,?,?,?,?,?)').run(id, manifest.name, manifest.created_at, manifest.last_used_at ?? null, manifest.paused_at ?? null, manifest.default_kind ?? null, manifest.grantee ?? null, JSON.stringify(manifest.metadata ?? {}));
-            cachedStatement(db, 'INSERT INTO scope_owners(owner_key,kind,root,profile_id) VALUES(?,?,?,?)').run(`profile:${id}`, 'profile', canonicalRoot(profileSpace(manifest.grantee ?? 'app:terminal', id).memory), id);
+            cachedStatement(db, 'INSERT INTO scope_owners(owner_key,kind,root,profile_id) VALUES(?,?,?,?)').run(`profile:${id}`, 'profile', canonicalRoot(profileSpace(manifest.grantee ?? 'app:terminal', id).dir), id);
             const project = cachedStatement(db, 'INSERT INTO profile_projects(profile_id,path,position) VALUES(?,?,?)');
             const cap = cachedStatement(db, 'INSERT INTO legacy_project_caps(profile_id,path,memory) VALUES(?,?,?)');
             manifest.projects.forEach((p, position) => { project.run(id, p.path, position); if (p.memory !== undefined && p.memory !== 'content')

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

@@ -31,7 +31,7 @@ export function pausedProfileIds(root) {
 export function insertStoredProfile(root, profile) {
     withScopedWrite(store(root), (db) => {
         cachedStatement(db, 'INSERT INTO profiles(id,name,created_at,last_used_at,paused_at,default_kind,grantee,metadata_json,delivery_limits_json) VALUES(?,?,?,?,?,?,?,?,?)').run(profile.profileId, profile.manifest.name, profile.manifest.created_at, profile.manifest.last_used_at, profile.manifest.paused_at, profile.manifest.default_kind ?? null, profile.manifest.grantee ?? null, JSON.stringify(profile.manifest.metadata ?? {}), JSON.stringify(profile.manifest.delivery_limits ?? {}));
-        cachedStatement(db, 'INSERT INTO scope_owners(owner_key,kind,root,profile_id) VALUES(?,?,?,?)').run(`profile:${profile.profileId}`, 'profile', canonicalRoot(profileSpace(profile.manifest.grantee ?? 'app:terminal', profile.profileId).memory), profile.profileId);
+        cachedStatement(db, 'INSERT INTO scope_owners(owner_key,kind,root,profile_id) VALUES(?,?,?,?)').run(`profile:${profile.profileId}`, 'profile', canonicalRoot(profileSpace(profile.manifest.grantee ?? 'app:terminal', profile.profileId).dir), profile.profileId);
         const insert = cachedStatement(db, 'INSERT INTO profile_projects(profile_id,path,position) VALUES(?,?,?)');
         profile.manifest.projects.forEach((project, position) => insert.run(profile.profileId, project.path, position));
     });

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

@@ -21,7 +21,10 @@ function ensureOwner(db, owner, access) {
     }
     if (row.root === owner.root)
         return;
-    if (owner.kind !== 'project' || owner.store.kind !== 'project' || owner.store.root !== owner.root) {
+    // A profile row is keyed by its id, checked above; its recorded root is a note of where the folder was. A profile
+    // folder that moved (`<app>/memory/profiles/<id>` → `<app>/profiles/<id>`) is rebound by the first write.
+    const profileMoved = owner.kind === 'profile' && owner.profileId !== undefined;
+    if (!profileMoved && (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')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.458",
+  "version": "0.3.460",
   "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",