@north-light/api 0.3.483 → 0.3.484

package/dist/api/client.d.ts

@@ -22,6 +22,7 @@ import type { FileEncoding, FileListDTO, FilePeekDTO, FileWriteDTO } from './dto
 import type { BashRunDTO, BashRunParams } from './dto/bash.js';
 import type { EdgesDTO, EdgesQuery, ObjectListDTO, ObjectListRequest, ObjectReadDTO, ObjectReadQuery, ObjectSearchDTO, ObjectSearchRequest, UnwatchQuery, UnwatchResultDTO, WatchRequest, WatchResultDTO } from './dto/objects.js';
 import type { DocDeletedDTO, DocEditRequest, DocEditedDTO, DocHistoryDTO, DocHistoryQuery, DocLintDTO, DocLintRequest, DocMoveRequest, DocMovedDTO, DocWriteRequest, DocWrittenDTO, ReconcilePackagesDTO } from './dto/docs.js';
+import type { PluginAppTokenDTO, PluginCallHeadersDTO, PluginCallHeadersRequestDTO } from './dto/plugins.js';
 import type { BackgroundedJobDTO, BackgroundedJobRequest, DeliveryDryRunRequest, DeliveryRequest, DeliveryResponse } from './dto/delivery.js';
 import type { ChatInventoryDTO, ProspectiveChatInventoryDTO, ProspectiveChatInventoryQuery } from './dto/chat-inventory.js';
 import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredentialRequest, CompleteModelAuthFlowRequest, ModelAuthFlowCompletedDTO, ModelAuthFlowDTO, ModelAuthFlowStartedDTO, ModelAuthListDTO, ModelAuthReadinessDTO, ModelAuthReadinessQuery, StartModelAuthFlowRequest } from './dto/modelauth.js';
@@ -299,6 +300,11 @@ export declare class CrtrClient {
     readonly documents: {
         reconcilePackages: () => Promise<ReconcilePackagesDTO>;
     };
+    /** A plugin's `crtr_app_` credential and the headers crtrd adds to its local HTTP calls. */
+    readonly plugins: {
+        appToken: (name: string) => Promise<PluginAppTokenDTO>;
+        callHeaders: (name: string, request: PluginCallHeadersRequestDTO) => Promise<PluginCallHeadersDTO>;
+    };
     /** The broker's delivery of one node activity. */
     nodeDelivery(id: string, request: DeliveryRequest): Promise<DeliveryResponse>;
     /** A person's dry run of one delivery activity, for a live or hypothetical node. Writes nothing. */

package/dist/api/client.js

@@ -529,6 +529,11 @@ export class CrtrClient {
     documents = {
         reconcilePackages: () => this.request('POST', routes.documentsReconcilePackages()),
     };
+    /** A plugin's `crtr_app_` credential and the headers crtrd adds to its local HTTP calls. */
+    plugins = {
+        appToken: (name) => this.request('GET', routes.pluginAppToken(name)),
+        callHeaders: (name, request) => this.request('POST', routes.pluginCallHeaders(name), request),
+    };
     /** The broker's delivery of one node activity. */
     nodeDelivery(id, request) {
         return this.request('POST', routes.nodeDelivery(this.nodePath(id)), request);

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.9";
+export declare const CONTRACT_LEVEL = "1.10";
 /** 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.9';
+export const CONTRACT_LEVEL = '1.10';
 /** 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/custom-objects.d.ts

@@ -1,3 +1,4 @@
+import type { PrivacyName } from './objects.js';
 export interface CustomEventSpecDTO {
     level: number;
     supersedes?: boolean;
@@ -13,9 +14,12 @@ export interface RegisterCustomObjectRequestDTO {
     name: string;
     owner?: string;
     description: string;
-    events: Record<string, CustomEventSpecDTO>;
+    /** Required unless an installed plugin declares the kind; then a register without it creates only the instance. */
+    events?: Record<string, CustomEventSpecDTO>;
     receiver?: CustomReceiverDTO;
     rotate_token?: boolean;
+    /** Who can read the instance: `public` (default), `friends` or `private`. Setting it on an existing instance changes it. */
+    privacy?: PrivacyName;
 }
 export interface RegisterCustomObjectResponseDTO {
     id: string;

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

@@ -139,4 +139,30 @@ export interface ReconcilePackagesDTO {
         reason: string;
         movedTo?: string;
     }>;
+    /** `object_kinds` the installed plugins declared: what applied, what another owner holds, which plugins are invalid */
+    kinds?: {
+        applied: Array<{
+            plugin: string;
+            kind: string;
+            outcome: 'inserted' | 'updated' | 'unchanged';
+        }>;
+        refused: Array<{
+            plugin: string;
+            kind: string;
+            code: 'kind_owned';
+            message: string;
+        }>;
+        invalid: Array<{
+            plugin: string;
+            error: string;
+        }>;
+    };
+    /** the `crtr_app_` tokens after this pass: who holds one (with its scopes) and whose was removed */
+    tokens?: {
+        granted: Array<{
+            plugin: string;
+            scopes: string[];
+        }>;
+        revoked: string[];
+    };
 }

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

@@ -6,6 +6,22 @@ export interface ObjectOwnerDTO {
     type: OwnerTypeName;
     handle: string;
 }
+/** A custom kind's declaration, carried with an object so another machine can hold a stub of it. It grants nothing. */
+export interface ObjectKindDeclDTO {
+    name: string;
+    description: string;
+    events: Record<string, {
+        level: number;
+        supersedes?: boolean;
+    }>;
+    owner: {
+        id: string;
+        type: 'person' | 'app' | 'repo' | 'profile';
+        scheme: string | null;
+        external_id: string | null;
+        handle: string;
+    };
+}
 export interface ObjectDTO {
     id: string;
     /** The object's kind name: `document`, `node`, `job`, `person`, `app`, `repo`, `profile`, or a later kind. */
@@ -17,6 +33,8 @@ export interface ObjectDTO {
     preview: string;
     created_at: string;
     deleted_at: string | null;
+    /** Present on an instance of a custom kind. */
+    kind_decl?: ObjectKindDeclDTO;
 }
 export interface DocHeadDTO {
     rev_id: string;
@@ -171,11 +189,13 @@ export interface WatchRequest {
     patterns?: string[];
     config?: ListenConfigDTO;
     filter?: Record<string, unknown>;
-    watcher?: string;
+    watcher?: string; /** With `watcher`: the machine of the account that homes that node (a node not on this machine). */
+    watcher_machine?: string;
 }
 export interface UnwatchQuery {
     pattern?: string;
     watcher?: string;
+    watcher_machine?: string;
 }
 export interface WatchResultDTO {
     object: ObjectDTO;

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

@@ -0,0 +1,22 @@
+/** `GET /v1/plugins/:name/app-token`. */
+export interface PluginAppTokenDTO {
+    /** The plugin's `crtr_app_` bearer for crtrd's `/v1` API. */
+    token: string;
+    /** The crtrd unix socket to present it on. */
+    socket: string;
+}
+/** `POST /v1/plugins/:name/call-headers`. Digests only: neither the body nor any header value reaches crtrd. */
+export interface PluginCallHeadersRequestDTO {
+    method: string;
+    url: string;
+    /** Lowercase hex sha256 of the exact body bytes sent (of "" when none). */
+    body_sha256: string;
+    /** Lowercase names of the headers the signature covers, sorted. */
+    header_names: string[];
+    /** Lowercase hex sha256 over `<name>:<value>\n` for each name in `header_names`. */
+    headers_sha256: string;
+}
+export interface PluginCallHeadersDTO {
+    /** `Crtr-Caller`, and `Crtr-Signature` when the call qualifies for signing. */
+    headers: Record<string, string>;
+}

package/dist/api/dto/plugins.js

@@ -0,0 +1,5 @@
+// Plugin credential routes: the app token a plugin's own service or exec leaf uses, and the headers crtrd adds to a
+// local HTTP plugin call.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export {};

package/dist/api/index.d.ts

@@ -48,4 +48,5 @@ export * from './dto/review-comments.js';
 export * from './dto/chat-inventory.js';
 export * from './dto/analytics.js';
 export * from './dto/custom-objects.js';
+export * from './dto/plugins.js';
 export type { WatchRequest, WatchResultDTO, UnwatchQuery, UnwatchResultDTO } from './dto/objects.js';

package/dist/api/index.js

@@ -45,3 +45,4 @@ export * from './dto/review-comments.js';
 export * from './dto/chat-inventory.js';
 export * from './dto/analytics.js';
 export * from './dto/custom-objects.js';
+export * from './dto/plugins.js';

package/dist/api/routes.d.ts

@@ -160,5 +160,7 @@ export declare const routes: {
     readonly docMove: (ref: string) => string;
     readonly docHistory: (ref: string) => string;
     readonly docsLint: () => string;
+    readonly pluginAppToken: (name: string) => string;
+    readonly pluginCallHeaders: (name: string) => string;
     readonly documentsReconcilePackages: () => string;
 };

package/dist/api/routes.js

@@ -193,5 +193,7 @@ export const routes = {
     docMove: (ref) => `${V}/docs/${encodeURIComponent(ref)}/move`,
     docHistory: (ref) => `${V}/docs/${encodeURIComponent(ref)}/history`,
     docsLint: () => `${V}/docs/lint`,
+    pluginAppToken: (name) => `${V}/plugins/${encodeURIComponent(name)}/app-token`,
+    pluginCallHeaders: (name) => `${V}/plugins/${encodeURIComponent(name)}/call-headers`,
     documentsReconcilePackages: () => `${V}/documents/reconcile-packages`,
 };

package/dist/core/command-plugins/bundle.d.ts

@@ -1,5 +1,5 @@
 import { type ValidatedCommandManifest } from '../../api/command-manifest/manifest.js';
-import type { KindConfig, MemoryExtensionDeclarations, PageComponentRegistration, PluginBundle, PluginManifest, Scope } from '../../types.js';
+import type { KindConfig, MemoryExtensionDeclarations, ObjectKindDeclaration, PageComponentRegistration, PluginBundle, PluginManifest, Scope } from '../../types.js';
 import { type BundleTransport } from './endpoint.js';
 /** Who may call a capability provider's tool group (contract 3). */
 export type ProviderGroupWho = 'own' | 'user' | 'allowlist' | 'any';
@@ -51,6 +51,9 @@ export interface ValidatedBundle {
     /** Plugin-owned memory metadata declarations copied into the synthesized
      * installed manifest alongside the archive's memory documents. */
     memory_extensions?: MemoryExtensionDeclarations;
+    /** Canvas object kinds and scopes declared in `bundle.json` (optional), copied into the synthesized manifest. */
+    object_kinds?: Record<string, ObjectKindDeclaration>;
+    scopes?: string[];
     commands: ValidatedCommandManifest;
     commandsBytes: Uint8Array;
     directories: ReadonlyArray<{

package/dist/core/command-plugins/bundle.js

@@ -8,13 +8,14 @@ import { general } from '../errors.js';
 import { atomicWriteJson, atomicWriteText, ensureDir, nowIso, pathExists, removePath, syncDirectory, syncTree } from '../fs-utils.js';
 import { invalidPageComponentsReasons, normalizePageComponents } from '../human/page-catalog.js';
 import { validateMemoryExtensionDeclarations } from '../plugin-extensions.js';
+import { objectBlocksShapeReasons } from '../plugin-objects-manifest.js';
 import { validateBundleTransport } from './endpoint.js';
 /** A capability provider id or tool group id: contract 1's `<id>` grammar. */
 const PROVIDER_ID = /^[A-Za-z0-9_-]{1,64}$/;
 const PROVIDER_KEYS = new Set(['id', 'major', 'groups']);
 const PROVIDER_GROUP_KEYS = new Set(['group', 'consent_line', 'rate', 'who', 'allowlist']);
 const PROVIDER_WHO = new Set(['own', 'user', 'allowlist', 'any']);
-const BUNDLE_KEYS = new Set(['bundleVersion', 'kinds', 'page_components', 'memory_extensions', 'version', 'transport', 'provider']);
+const BUNDLE_KEYS = new Set(['bundleVersion', 'kinds', 'page_components', 'memory_extensions', 'version', 'transport', 'provider', 'object_kinds', 'scopes']);
 function issue(code, message, received, expected, next, path) {
     return { code, message, received, expected, next, ...(path !== undefined ? { path } : {}) };
 }
@@ -275,7 +276,7 @@ function parseBundleMetadata(bytes) {
     const unknownKeys = Object.keys(record).filter((key) => !BUNDLE_KEYS.has(key));
     if (record['bundleVersion'] !== 1 || unknownKeys.length > 0) {
         return {
-            issue: bundleInvalid('bundle.json must contain bundleVersion 1 and at most version, transport, provider, kinds, page_components, and memory_extensions', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optional version, transport, provider, kinds, page_components, and memory_extensions', 'Set bundle.json to {"bundleVersion":1} plus optional contribution blocks.', 'bundle.json'),
+            issue: bundleInvalid('bundle.json must contain bundleVersion 1 and at most version, transport, provider, kinds, page_components, memory_extensions, object_kinds, and scopes', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optional version, transport, provider, kinds, page_components, memory_extensions, object_kinds, and scopes', 'Set bundle.json to {"bundleVersion":1} plus optional contribution blocks.', 'bundle.json'),
         };
     }
     // Install-time strictness: a bad block fails the install loudly here, because
@@ -297,6 +298,15 @@ function parseBundleMetadata(bytes) {
             };
         }
     }
+    const objectReasons = objectBlocksShapeReasons(record);
+    if (record['provider'] !== undefined && record['scopes'] !== undefined) {
+        objectReasons.push('scopes is for local plugins; a provider gets its scopes from directory consent');
+    }
+    if (objectReasons.length > 0) {
+        return {
+            issue: bundleInvalid('bundle.json object_kinds or scopes block is invalid', objectReasons.join('; '), 'object_kinds keyed by kind name with description, events and optional read.command; scopes an array of crtr:objects:<verb>:<target> strings (local plugins only)', 'Fix the object_kinds and scopes blocks in bundle.json.', 'bundle.json'),
+        };
+    }
     let memoryExtensions;
     if (record['memory_extensions'] !== undefined) {
         try {
@@ -342,6 +352,8 @@ function parseBundleMetadata(bytes) {
         ...(record['kinds'] !== undefined ? { kinds: record['kinds'] } : {}),
         ...(record['page_components'] !== undefined ? { page_components: normalizePageComponents(record['page_components']) } : {}),
         ...(memoryExtensions !== undefined ? { memory_extensions: memoryExtensions } : {}),
+        ...(record['object_kinds'] !== undefined ? { object_kinds: record['object_kinds'] } : {}),
+        ...(record['scopes'] !== undefined ? { scopes: record['scopes'] } : {}),
     };
 }
 function parseCommands(bytes, reservedCoreNames, coreCommandPaths, extensibleCoreBranches = new Set()) {
@@ -421,6 +433,8 @@ export async function validatePluginBundle(archive, options) {
             ...(metadata.kinds !== undefined ? { kinds: metadata.kinds } : {}),
             ...(metadata.page_components !== undefined ? { page_components: metadata.page_components } : {}),
             ...(metadata.memory_extensions !== undefined ? { memory_extensions: metadata.memory_extensions } : {}),
+            ...(metadata.object_kinds !== undefined ? { object_kinds: metadata.object_kinds } : {}),
+            ...(metadata.scopes !== undefined ? { scopes: metadata.scopes } : {}),
             commands: commandValidation.commands,
             commandsBytes: commands.bytes,
             directories: parsed.members
@@ -534,6 +548,9 @@ export async function installBundleArchive(name, raw, options) {
         // later archive that no longer declares them is what retires them.
         ...(validated.page_components !== undefined ? { page_components: validated.page_components } : {}),
         ...(validated.memory_extensions !== undefined ? { memory_extensions: validated.memory_extensions } : {}),
+        // Canvas object kinds and scopes, copied like page_components: a later archive that drops a block drops it here.
+        ...(validated.object_kinds !== undefined ? { object_kinds: validated.object_kinds } : {}),
+        ...(validated.scopes !== undefined ? { scopes: validated.scopes } : {}),
         ...(validated.hooks !== undefined ? { hooks: 'hooks.json', hookExecutable: 'hooks/dispatch' } : {}),
         // A capability provider's block, read by provider composition and calls.
         ...(validated.provider !== undefined ? { provider: validated.provider } : {}),

package/dist/core/command-plugins/endpoint.d.ts

@@ -12,6 +12,10 @@ export interface EndpointValidation {
     isValid: boolean;
     errors: string[];
 }
+/** Hosts `http:` is allowed for: loopback, Docker's host alias, and any
+ *  `*.localhost` name (RFC 6761 reserves it for local use; the local
+ *  directory and provider stacks serve `http://<svc>.localhost:<port>`). */
+export declare function isLoopbackHostname(hostname: string): boolean;
 export declare function validateEndpoint(endpoint: unknown): EndpointValidation;
 export declare function normalizeEndpoint(endpoint: string): string;
 export declare function validateHttpPluginTransport(raw: unknown): {

package/dist/core/command-plugins/endpoint.js

@@ -2,7 +2,7 @@ import { validateEnvVarName } from '../env-name.js';
 /** Hosts `http:` is allowed for: loopback, Docker's host alias, and any
  *  `*.localhost` name (RFC 6761 reserves it for local use; the local
  *  directory and provider stacks serve `http://<svc>.localhost:<port>`). */
-function isLoopbackHostname(hostname) {
+export function isLoopbackHostname(hostname) {
     return hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1' || hostname === 'host.docker.internal';
 }
 export function validateEndpoint(endpoint) {

package/dist/core/plugin-objects-manifest.d.ts

@@ -0,0 +1,35 @@
+import type { DeclLeaf, DeclNode } from '../api/command-manifest/schema.js';
+import type { PluginManifest } from '../types.js';
+/**
+ * The `object_kinds` and `scopes` blocks of a plugin manifest (`plugin.json`, `bundle.json`) and the one
+ * validator every install, update, enable, provider-bundle and reconcile path shares. Canvas-free by
+ * design: the CLI and the bundle parser import it, so it must not reach `node:sqlite` or the canvas.
+ */
+export declare const KIND: RegExp;
+export declare const LOCAL: RegExp;
+/** A kind's first segment may not be one of the built-in object types. */
+export declare const RESERVED_KIND_ROOTS: readonly string[];
+export declare const MAX_KIND_EVENTS = 64;
+export declare const MIN_EVENT_LEVEL = 1;
+export declare const MAX_EVENT_LEVEL = 10;
+/** Reasons a catalog (`events` map) is invalid; shared with `registerCustomObject`. */
+export declare function eventCatalogReasons(events: unknown, where: string): string[];
+/** The JSON shape of both blocks of a raw manifest record, independent of the plugin's name and commands. */
+export declare function objectBlocksShapeReasons(record: Record<string, unknown>): string[];
+/**
+ * The full check. `leafPaths` holds the space-joined path of every leaf below the plugin's root command
+ * (`page read` for plugin `search`'s leaf `search page read`); `streamingLeafPaths` holds those declared `rest.streaming: true`.
+ */
+export declare function objectBlocksReasons(manifest: Pick<PluginManifest, 'object_kinds' | 'scopes' | 'provider'>, context: {
+    name: string;
+    leafPaths: ReadonlySet<string>;
+    streamingLeafPaths: ReadonlySet<string>;
+}): string[];
+/** The manifest carries an `object_kinds` or `scopes` block, whether or not it is valid or the plugin holds a token. */
+export declare function declaresObjectBlocks(manifest: Pick<PluginManifest, 'object_kinds' | 'scopes'>): boolean;
+/** A user plugin holds a `crtr_app_` token when it is not a provider and declares kinds or scopes, or serves over HTTP. */
+export declare function needsAppToken(manifest: Pick<PluginManifest, 'object_kinds' | 'scopes' | 'provider' | 'transport'>): boolean;
+/** The space-joined path of every leaf below the plugin's root command (`page read` for plugin `search`'s leaf `search page read`). */
+export declare function leafPathsBelowRoot(name: string, roots: ReadonlyArray<DeclNode<DeclLeaf>>): Set<string>;
+/** The leaves of `leafPathsBelowRoot` that declare `rest.streaming: true`. */
+export declare function streamingLeafPathsBelowRoot(name: string, roots: ReadonlyArray<DeclNode<DeclLeaf>>): Set<string>;

package/dist/core/plugin-objects-manifest.js

@@ -0,0 +1,159 @@
+import { parseScope } from '@north-light/identity';
+/**
+ * The `object_kinds` and `scopes` blocks of a plugin manifest (`plugin.json`, `bundle.json`) and the one
+ * validator every install, update, enable, provider-bundle and reconcile path shares. Canvas-free by
+ * design: the CLI and the bundle parser import it, so it must not reach `node:sqlite` or the canvas.
+ */
+export const KIND = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$/;
+export const LOCAL = /^[a-z][a-z0-9-]*$/;
+/** A kind's first segment may not be one of the built-in object types. */
+export const RESERVED_KIND_ROOTS = ['report', 'notice', 'node', 'job', 'document', 'person', 'app', 'repo', 'profile', 'action'];
+export const MAX_KIND_EVENTS = 64;
+export const MIN_EVENT_LEVEL = 1;
+export const MAX_EVENT_LEVEL = 10;
+const KIND_KEYS = new Set(['description', 'events', 'read']);
+const EVENT_KEYS = new Set(['level', 'supersedes']);
+const SCOPE_VERBS = /^crtr:objects:(?:read|watch|link|write):/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Reasons a catalog (`events` map) is invalid; shared with `registerCustomObject`. */
+export function eventCatalogReasons(events, where) {
+    if (!isRecord(events))
+        return [`${where} events must be an object`];
+    const reasons = [];
+    const entries = Object.entries(events);
+    if (entries.length > MAX_KIND_EVENTS)
+        reasons.push(`${where} declares more than ${MAX_KIND_EVENTS} events`);
+    for (const [local, spec] of entries) {
+        const at = `${where} event ${JSON.stringify(local)}`;
+        if (!LOCAL.test(local))
+            reasons.push(`${at} is not a valid event name`);
+        if (!isRecord(spec)) {
+            reasons.push(`${at} must be an object { level, supersedes? }`);
+            continue;
+        }
+        for (const key of Object.keys(spec))
+            if (!EVENT_KEYS.has(key))
+                reasons.push(`${at} has unknown key ${JSON.stringify(key)}`);
+        const level = spec['level'];
+        if (typeof level !== 'number' || !Number.isInteger(level) || level < MIN_EVENT_LEVEL || level > MAX_EVENT_LEVEL)
+            reasons.push(`${at} level must be an integer ${MIN_EVENT_LEVEL}-${MAX_EVENT_LEVEL}`);
+        if (spec['supersedes'] !== undefined && typeof spec['supersedes'] !== 'boolean')
+            reasons.push(`${at} supersedes must be a boolean`);
+    }
+    return reasons;
+}
+/** The JSON shape of both blocks of a raw manifest record, independent of the plugin's name and commands. */
+export function objectBlocksShapeReasons(record) {
+    const reasons = [];
+    const kinds = record['object_kinds'];
+    if (kinds !== undefined) {
+        if (!isRecord(kinds))
+            reasons.push('object_kinds must be an object keyed by kind name');
+        else {
+            for (const [kind, decl] of Object.entries(kinds)) {
+                const where = `object_kinds ${JSON.stringify(kind)}`;
+                if (!KIND.test(kind))
+                    reasons.push(`${where} is not a valid kind name (<plugin>.<name>, lowercase)`);
+                else if (RESERVED_KIND_ROOTS.includes(kind.split('.')[0]))
+                    reasons.push(`${where} uses a reserved first segment`);
+                if (!isRecord(decl)) {
+                    reasons.push(`${where} must be an object { description, events, read? }`);
+                    continue;
+                }
+                for (const key of Object.keys(decl))
+                    if (!KIND_KEYS.has(key))
+                        reasons.push(`${where} has unknown key ${JSON.stringify(key)}`);
+                if (typeof decl['description'] !== 'string' || decl['description'].trim() === '')
+                    reasons.push(`${where} description must be non-empty text`);
+                reasons.push(...eventCatalogReasons(decl['events'], where));
+                const read = decl['read'];
+                if (read !== undefined) {
+                    const command = isRecord(read) ? read['command'] : undefined;
+                    if (!isRecord(read) || Object.keys(read).some((key) => key !== 'command'))
+                        reasons.push(`${where} read must be { command: [leaf path] }`);
+                    else if (!Array.isArray(command) || command.length === 0 || command.some((part) => typeof part !== 'string' || part === ''))
+                        reasons.push(`${where} read.command must be a non-empty array of command names`);
+                }
+            }
+        }
+    }
+    const scopes = record['scopes'];
+    if (scopes !== undefined) {
+        if (!Array.isArray(scopes) || scopes.some((scope) => typeof scope !== 'string'))
+            reasons.push('scopes must be an array of scope strings');
+    }
+    return reasons;
+}
+/**
+ * The full check. `leafPaths` holds the space-joined path of every leaf below the plugin's root command
+ * (`page read` for plugin `search`'s leaf `search page read`); `streamingLeafPaths` holds those declared `rest.streaming: true`.
+ */
+export function objectBlocksReasons(manifest, context) {
+    const reasons = objectBlocksShapeReasons(manifest);
+    if (reasons.length > 0)
+        return reasons;
+    const { name, leafPaths, streamingLeafPaths } = context;
+    for (const [kind, decl] of Object.entries(manifest.object_kinds ?? {})) {
+        if (kind.split('.')[0] !== name)
+            reasons.push(`object_kinds ${JSON.stringify(kind)} must start with the plugin name "${name}."`);
+        const command = decl.read?.command;
+        if (command !== undefined && !leafPaths.has(command.join(' ')))
+            reasons.push(`object_kinds ${JSON.stringify(kind)} read.command "${command.join(' ')}" is not a leaf of plugin "${name}"`);
+        else if (command !== undefined && streamingLeafPaths.has(command.join(' ')))
+            reasons.push(`object_kinds ${JSON.stringify(kind)} read.command "${command.join(' ')}" streams; a read is one {markdown} answer`);
+    }
+    const scopes = manifest.scopes ?? [];
+    if (manifest.scopes !== undefined && manifest.provider !== undefined)
+        reasons.push('scopes is for local plugins; a provider gets its scopes from directory consent');
+    for (const scope of scopes) {
+        try {
+            parseScope(scope);
+        }
+        catch {
+            reasons.push(`scope ${JSON.stringify(scope)} is not a recognized scope`);
+            continue;
+        }
+        if (!SCOPE_VERBS.test(scope))
+            reasons.push(`scope ${JSON.stringify(scope)} must be crtr:objects:<read|watch|link|write>:<target>`);
+        else if (scope.endsWith(`:app:${name}`))
+            reasons.push(`scope ${JSON.stringify(scope)} names the plugin's own space; an app needs no scope for its own objects`);
+    }
+    return reasons;
+}
+/** The manifest carries an `object_kinds` or `scopes` block, whether or not it is valid or the plugin holds a token. */
+export function declaresObjectBlocks(manifest) {
+    return manifest.object_kinds !== undefined || manifest.scopes !== undefined;
+}
+/** A user plugin holds a `crtr_app_` token when it is not a provider and declares kinds or scopes, or serves over HTTP. */
+export function needsAppToken(manifest) {
+    if (manifest.provider !== undefined)
+        return false;
+    return Object.keys(manifest.object_kinds ?? {}).length > 0 || (manifest.scopes?.length ?? 0) > 0 || manifest.transport?.kind === 'http';
+}
+/** The space-joined path of every leaf below the plugin's root command (`page read` for plugin `search`'s leaf `search page read`). */
+export function leafPathsBelowRoot(name, roots) {
+    return collectLeafPaths(name, roots, () => true);
+}
+/** The leaves of `leafPathsBelowRoot` that declare `rest.streaming: true`. */
+export function streamingLeafPathsBelowRoot(name, roots) {
+    return collectLeafPaths(name, roots, (leaf) => 'rest' in leaf && leaf.rest.streaming === true);
+}
+function collectLeafPaths(name, roots, include) {
+    const leafPaths = new Set();
+    const walk = (node, prefix) => {
+        if (node.kind === 'leaf') {
+            if (include(node))
+                leafPaths.add([...prefix, node.name].join(' '));
+        }
+        else
+            for (const child of node.children)
+                walk(child, [...prefix, node.name]);
+    };
+    for (const root of roots)
+        if (root.name === name && root.kind === 'branch')
+            for (const child of root.children)
+                walk(child, []);
+    return leafPaths;
+}

package/dist/types.d.ts

@@ -60,6 +60,18 @@ export type MemoryExtensionDeclaration = BooleanMemoryExtensionDeclaration | Str
 /** Field declarations owned by one plugin manifest. The plugin's `name` is
  * the namespace; keys here are its lowercase kebab-case local field names. */
 export type MemoryExtensionDeclarations = Record<string, MemoryExtensionDeclaration>;
+/** One canvas object kind a plugin declares in `object_kinds`. */
+export interface ObjectKindDeclaration {
+    description: string;
+    events: Record<string, {
+        level: number;
+        supersedes?: boolean;
+    }>;
+    /** A leaf path of the plugin's own commands, run to render an instance as markdown. */
+    read?: {
+        command: string[];
+    };
+}
 export interface PluginManifest {
     name: string;
     version?: string;
@@ -124,6 +136,10 @@ export interface PluginManifest {
     /** App-scoped env variables required by this plugin, collected during install. */
     env?: Record<string, import('./core/plugin-env.js').PluginEnvDeclaration>;
     transport?: PluginTransport;
+    /** Canvas object kinds this plugin declares, keyed by kind name (`<plugin>.<name>`). */
+    object_kinds?: Record<string, ObjectKindDeclaration>;
+    /** Canvas scopes (`crtr:objects:<verb>:<target>`) a local plugin's app credential holds. */
+    scopes?: string[];
     /** Archive source for a crouter-materialized HTTP plugin. Distinct from the invocation transport. */
     bundle?: PluginBundle;
     /** A capability provider's `bundle.json` `provider` block, copied by the

package/package.json

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