@north-light/crouter 0.3.216 → 0.3.218

package/dist/core/human/__tests__/page.test.js

@@ -78,3 +78,15 @@ test('final and partial response validation share slot-addressed rules', () => {
     assert.throws(() => validatePartialPageResponses(manifest, { choice: { selectedOptionIds: ['maybe'], comments: [] } }), /unknown option id "maybe"/);
     assert.throws(() => validatePartialPageResponses(manifest, { extra: {} }), /unknown or non-response-bearing slot id "extra"/);
 });
+// Which questions have a minimum is the author's call, and both defaults matter to a
+// renderer mirroring this rule: pick-many is answered by ticking nothing, pick-one is not.
+test('an empty answer is refused only where the question is required', () => {
+    const manifest = derivePageManifestFromDocument(page(`<UserQuestion id="risks" label="Tick everything that applies" body="Skip it if none do." mode="multi" options={[{ id: "data", label: "Data" }]} />
+      <UserQuestion id="lane" label="Which lane?" body="Ships tonight." mode="single" required={false} options={[{ id: "now", label: "Now" }]} />
+      <UserText id="window" label="Maintenance window" initialText="" required />`));
+    const empty = { risks: { selectedOptionIds: [], comments: [] }, lane: { selectedOptionIds: [], comments: [] }, window: { text: 'Sunday 02:00', edited: true } };
+    assert.deepEqual(validatePageResponses(manifest, empty), empty);
+    assert.throws(() => validatePageResponses(manifest, { ...empty, window: { text: '  ', edited: true } }), /slot "window" is required and was left empty/);
+    const required = derivePageManifestFromDocument(page('<UserQuestion id="risks" label="Tick everything that applies" body="At least one." mode="multi" required options={[{ id: "data", label: "Data" }]} />'));
+    assert.throws(() => validatePageResponses(required, { risks: { selectedOptionIds: [], comments: [] } }), /multi-select slot "risks" requires a selection/);
+});

package/dist/core/human/component-docs.js

@@ -55,6 +55,7 @@ Props
 Rules
 - \`<Step>\` elements are children of \`<Page>\`; step order is source order, and the ticket manifest records the step count.
 - A single-step page needs no \`<Step>\` at all — put the content directly in \`<Page>\`.
+- The reader sees one step at a time, so hold each step to one question or request for action, with the context that decision needs beside it. Several decisions means several steps, never one long scroll.
 
 Example
 \`\`\`jsx
@@ -79,12 +80,13 @@ Props
 - \`options\` — required nonempty array of \`{id:string (nonempty, unique), label:string (nonempty), description?:string, recommended?:boolean}\`.
 - \`recommended\` on one option marks it the suggested answer. At most one option per question may set it. The inbox shows it on the row, and when this question is the page's only response-bearing component the user can accept it from the list with one keystroke, without opening the page. Recommend when you have a view worth acting on; leave it off when the choice is genuinely theirs.
 - \`mode\` — required: \`single\` or \`multi\`.
+- \`required?:boolean\` — whether an empty answer is refused. Defaults to the mode: a \`single\` question must be answered, a \`multi\` one need not be, because leaving every box unticked says "none of these apply". Set \`required\` when the mode's default is wrong — \`required={false}\` on a \`single\` question the user may skip, \`required\` on a \`multi\` one where at least one tick is the point.
 - \`label\` — required nonempty string: the question itself, drawn as the bold first line.
 - \`body\` — required nonempty string: markdown rendered above the choices — the context under the question a label cannot carry. Display-only; contributes nothing to the response.
 - \`allowFreetext?:boolean\`, \`freetextLabel?:string\`, \`freetextPlaceholder?:string\` — adds a final "something else" choice, drawn as one more row with its own control and a field to write in rather than as a note on the question. It is exclusive on a \`single\` question (choosing it clears the selection, and choosing an option clears what was written) and just another box on a \`multi\` one. \`freetextLabel\` names that row, default "Something else".
 
 Response rules
-- \`selectedOptionIds\` contains unique known option ids. A \`single\` response has at most one selected id and requires exactly one selection or nonempty allowed \`freetext\`; a \`multi\` response requires a selection, comment, or nonempty allowed \`freetext\`.
+- \`selectedOptionIds\` contains unique known option ids; a \`single\` response has at most one. When the question is required, a \`single\` response needs exactly one selection or nonempty allowed \`freetext\`, and a \`multi\` response needs a selection, comment, or nonempty allowed \`freetext\`.
 - \`freetext\` is accepted only when \`allowFreetext:true\`.
 - ${COMMENT_SHAPE} UserQuestion accepts only \`option\` anchors; \`optionId\` must name a configured option.
 
@@ -116,6 +118,7 @@ Props
 - \`label?:string\` — the component's label; required by the multi-response page rule.
 - \`placeholder?:string\` — the hint shown while the field is empty.
 - \`singleLine?:boolean\` — swaps the writing surface for one compact form field.
+- \`required?:boolean\` — defaults false. When set, a field left empty (whitespace only) is refused, and the inbox marks it unanswered rather than sending it.
 
 The field is always writable; there is no read-only mode, and the config rejects an \`editable\` prop.
 
@@ -140,6 +143,7 @@ Props
 - \`rows?:\` array of \`{id:string (nonempty, unique), cells:Record<string,string|number|boolean|null>}\`. Rows are inline — map your data into this array in the module.
 - \`rowSelect?:"none"|"single"|"multi"\` — defaults to \`none\`.
 - \`columnSelect?:"none"|"single"|"multi"\` — defaults to \`none\`.
+- \`required?:boolean\` — defaults false. When set on a selectable table, a response selecting no row and no column is refused.
 - \`label?:string\` — the component's label; required by the multi-response page rule when the table is selectable.
 - \`body?:string\` — optional markdown rendered above the table. Display-only; it contributes nothing to the response.
 
@@ -169,6 +173,7 @@ Props
 - \`cards?:\` array of \`{id:string (nonempty, unique), title:string (nonempty), subtitle?:string, body?:string, tag?:string}\`. Cards are inline — map your data into this array in the module.
 - \`mode\` — required: \`single\` or \`multi\`.
 - \`columns?:2|3\` — optional layout column count.
+- \`required?:boolean\` — defaults false. When set, a response selecting no card is refused.
 - \`label?:string\` — the component's label; required by the multi-response page rule.
 - \`body?:string\` — optional markdown rendered above the cards. Display-only; it contributes nothing to the response.
 

package/dist/core/human/page-schema.d.ts

@@ -41,6 +41,7 @@ export declare const optionsConfigSchema: z.ZodObject<{
         single: "single";
         multi: "multi";
     }>;
+    required: z.ZodOptional<z.ZodBoolean>;
     allowFreetext: z.ZodOptional<z.ZodBoolean>;
     freetextLabel: z.ZodOptional<z.ZodString>;
     freetextPlaceholder: z.ZodOptional<z.ZodString>;
@@ -67,6 +68,7 @@ export declare const textConfigSchema: z.ZodObject<{
     initialText: z.ZodString;
     placeholder: z.ZodOptional<z.ZodString>;
     singleLine: z.ZodOptional<z.ZodBoolean>;
+    required: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type TextConfig = z.infer<typeof textConfigSchema>;
 export declare const textResponseSchema: z.ZodObject<{
@@ -119,6 +121,7 @@ export declare const tableConfigSchema: z.ZodObject<{
         single: "single";
         multi: "multi";
     }>>;
+    required: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type TableConfig = z.infer<typeof tableConfigSchema>;
 export declare const tableResponseSchema: z.ZodObject<{
@@ -167,6 +170,7 @@ export declare const cardsConfigSchema: z.ZodObject<{
         multi: "multi";
     }>;
     columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>]>>;
+    required: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type CardsConfig = z.infer<typeof cardsConfigSchema>;
 export declare const cardsResponseSchema: z.ZodObject<{
@@ -228,6 +232,14 @@ export interface PageManifest {
     slots: PageSlot[];
     source?: PageSource;
 }
+export declare const pageDeliverySchema: z.ZodObject<{
+    placement: z.ZodEnum<{
+        inline: "inline";
+        panel: "panel";
+    }>;
+    inbox: z.ZodBoolean;
+    reply: z.ZodBoolean;
+}, z.core.$strict>;
 export declare const BUILTIN_PAGE_CONFIG_SCHEMAS: Record<(typeof BUILTIN_PAGE_KINDS)[number], z.ZodType>;
 export declare const BUILTIN_PAGE_RESPONSE_SCHEMAS: Partial<Record<(typeof BUILTIN_PAGE_KINDS)[number], z.ZodType>>;
 export declare function issueText(error: z.ZodError): string;
@@ -266,6 +278,8 @@ export declare function validateAuthoredPageManifest(parsed: unknown, productCom
 export declare function createPageManifestSchema(): z.ZodType<PageManifest>;
 export declare const pageManifestSchema: z.ZodType<PageManifest, unknown, z.core.$ZodTypeInternals<PageManifest, unknown>>;
 export type PageResponses = Record<string, SlotResponse>;
+/** A picker's minimum: authored `required` wins, else the mode's own reading of an empty answer. */
+export declare function optionsRequired(config: OptionsConfig): boolean;
 /** Validate a complete final response map. */
 export declare function validatePageResponses(manifest: PageManifest, responses: unknown): PageResponses;
 /** Validate an autosaved response map, permitting omitted response-bearing components. */

package/dist/core/human/page-schema.js

@@ -28,6 +28,9 @@ export const optionsConfigSchema = z.object({
     body: z.string().optional(),
     options: z.array(optionSchema).min(1).superRefine((items, ctx) => uniqueIds(items, ctx, 'option')),
     mode: z.enum(['single', 'multi']),
+    // Defaults with the mode: a radio group means "pick one", while an empty checkbox
+    // list is itself an answer ("none of these apply").
+    required: z.boolean().optional(),
     allowFreetext: z.boolean().optional(),
     freetextLabel: z.string().optional(),
     freetextPlaceholder: z.string().optional(),
@@ -40,7 +43,7 @@ export const optionsResponseSchema = z.object({ selectedOptionIds: z.array(itemI
 // Text is a writing surface, always: its whole point is the string the user hands back, so
 // there is no read-only mode. `singleLine` only swaps the multi-line surface for one compact
 // form field — a subject line, a name, a URL.
-export const textConfigSchema = z.object({ label: z.string().optional(), initialText: z.string(), placeholder: z.string().optional(), singleLine: z.boolean().optional() }).strict();
+export const textConfigSchema = z.object({ label: z.string().optional(), initialText: z.string(), placeholder: z.string().optional(), singleLine: z.boolean().optional(), required: z.boolean().optional() }).strict();
 export const textResponseSchema = z.object({ text: z.string(), edited: z.boolean() }).strict();
 export const tableColumnSchema = z.object({ id: itemIdSchema, label: z.string().min(1), align: z.enum(['left', 'right']).optional(), mono: z.boolean().optional() }).strict();
 export const tableCellSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
@@ -53,6 +56,7 @@ const tableConfigFields = {
     rows: tableRowsSchema.optional(),
     rowSelect: selectModeSchema.default('none'),
     columnSelect: selectModeSchema.default('none'),
+    required: z.boolean().optional(),
 };
 /** Table config: its data is always embedded. */
 export const tableConfigSchema = z.object(tableConfigFields).strict();
@@ -65,6 +69,7 @@ const cardsConfigFields = {
     cards: cardsSchema.optional(),
     mode: z.enum(['single', 'multi']),
     columns: z.union([z.literal(2), z.literal(3)]).optional(),
+    required: z.boolean().optional(),
 };
 /** Cards config: its data is always embedded. */
 export const cardsConfigSchema = z.object(cardsConfigFields).strict();
@@ -81,14 +86,14 @@ const chartConfigFields = {
 /** Chart config: its data is always embedded. */
 export const chartConfigSchema = z.object(chartConfigFields).strict();
 const sourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), emittedAt: z.string().datetime({ offset: true }).optional(), profileName: z.string().optional(), nodeId: z.string().optional() }).strict();
-const deliverySchema = z.object({ placement: z.enum(['inline', 'panel']), inbox: z.boolean(), reply: z.boolean() }).strict();
+export const pageDeliverySchema = z.object({ placement: z.enum(['inline', 'panel']), inbox: z.boolean(), reply: z.boolean() }).strict();
 const rawSlotSchema = z.object({ id: idSchema.optional(), kind: z.string().min(1), step: z.number().int().nonnegative(), config: jsonObjectSchema, unvalidated: z.literal(true).optional(), display: z.literal(true).optional() }).strict();
 const rawPageManifestSchema = z.object({
     schema: z.literal('crtr.page/v2'),
     dialect: z.enum(['jsx', 'html']),
     title: z.string().trim().min(1),
     subtitle: z.string().optional(),
-    delivery: deliverySchema,
+    delivery: pageDeliverySchema,
     document: z.enum(['page.tsx', 'page.html']),
     steps: z.number().int().positive(),
     slots: z.array(rawSlotSchema),
@@ -254,6 +259,10 @@ function validateComments(slot, comments) {
         throw new Error(`slot "${slot.id}" does not allow comment anchor kind "${anchor.kind}"`);
     }
 }
+/** A picker's minimum: authored `required` wins, else the mode's own reading of an empty answer. */
+export function optionsRequired(config) {
+    return config.required ?? config.mode === 'single';
+}
 function parseResponse(slot, raw) {
     if (slot.unvalidated === true) {
         const result = jsonObjectSchema.safeParse(raw);
@@ -276,10 +285,12 @@ function parseResponse(slot, raw) {
         if (config.mode === 'single' && response.selectedOptionIds.length > 1)
             throw new Error(`slot "${slot.id}" is single-select but received ${response.selectedOptionIds.length} option ids`);
         const hasFreetext = config.allowFreetext === true && (response.freetext?.trim() ?? '') !== '';
-        if (config.mode === 'single' && response.selectedOptionIds.length !== 1 && !hasFreetext)
-            throw new Error(`single-select slot "${slot.id}" requires exactly one selection or nonempty allowed freetext`);
-        if (config.mode === 'multi' && response.selectedOptionIds.length === 0 && response.comments.length === 0 && !hasFreetext)
-            throw new Error(`multi-select slot "${slot.id}" requires a selection, comment, or nonempty allowed freetext`);
+        if (optionsRequired(config)) {
+            if (config.mode === 'single' && response.selectedOptionIds.length !== 1 && !hasFreetext)
+                throw new Error(`single-select slot "${slot.id}" requires exactly one selection or nonempty allowed freetext`);
+            if (config.mode === 'multi' && response.selectedOptionIds.length === 0 && response.comments.length === 0 && !hasFreetext)
+                throw new Error(`multi-select slot "${slot.id}" requires a selection, comment, or nonempty allowed freetext`);
+        }
         validateComments(slot, response.comments);
         return response;
     }
@@ -287,6 +298,8 @@ function parseResponse(slot, raw) {
         const result = textResponseSchema.safeParse(raw);
         if (!result.success)
             throw new Error(`invalid response for slot "${slot.id}": ${issueText(result.error)}`);
+        if (slot.config.required === true && result.data.text.trim() === '')
+            throw new Error(`slot "${slot.id}" is required and was left empty`);
         return result.data;
     }
     if (slot.kind === 'table') {
@@ -305,6 +318,8 @@ function parseResponse(slot, raw) {
         for (const id of response.selectedColumnIds)
             if (!columnIds.has(id))
                 throw new Error(`slot "${slot.id}" selects unknown column id "${id}"`);
+        if (config.required === true && response.selectedRowIds.length === 0 && response.selectedColumnIds.length === 0)
+            throw new Error(`slot "${slot.id}" is required and nothing is selected`);
         if ((config.rowSelect === 'none' && response.selectedRowIds.length > 0) || (config.rowSelect === 'single' && response.selectedRowIds.length > 1))
             throw new Error(`slot "${slot.id}" response violates row select mode "${config.rowSelect}"`);
         if ((config.columnSelect === 'none' && response.selectedColumnIds.length > 0) || (config.columnSelect === 'single' && response.selectedColumnIds.length > 1))
@@ -324,6 +339,8 @@ function parseResponse(slot, raw) {
                 throw new Error(`slot "${slot.id}" selects unknown card id "${id}"`);
         if (config.mode === 'single' && response.selectedCardIds.length > 1)
             throw new Error(`slot "${slot.id}" is single-select but received ${response.selectedCardIds.length} card ids`);
+        if (config.required === true && response.selectedCardIds.length === 0)
+            throw new Error(`slot "${slot.id}" is required and nothing is selected`);
         return response;
     }
     throw new Error(`slot "${slot.id}" kind "${slot.kind}" does not accept a response`);

package/dist/core/human/page.d.ts

@@ -12,3 +12,5 @@ export declare function deriveHtmlPageManifest(document: string, source?: PageSo
 export declare function derivePageManifest(sourceFile: string, productComponents?: ProductPageComponents, source?: PageSource, delivery?: PageDelivery): PageManifest;
 /** Read and validate page.json from a ticket directory. */
 export declare function parsePage(dir: string): PageManifest;
+/** Read only the stable delivery envelope without interpreting component config. */
+export declare function parsePageDelivery(dir: string): PageDelivery;

package/dist/core/human/page.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { transformSync } from 'esbuild';
 import ts from 'typescript';
 import { BUILTIN_KIND_BY_TAG, BUILTIN_PAGE_COMPONENT_TAGS, DISPLAY_PAGE_COMPONENT_TAGS, pageComponentTag } from './page-catalog.js';
-import { isResponseBearingSlot, validateAuthoredPageManifest, validatePageManifest } from './page-schema.js';
+import { isResponseBearingSlot, pageDeliverySchema, validateAuthoredPageManifest, validatePageManifest } from './page-schema.js';
 import { evaluatePageTree, jsonProps } from './page-eval.js';
 import { PageAuthoringError } from './page-errors.js';
 export { PageAuthoringError };
@@ -174,14 +174,25 @@ export function deriveHtmlPageManifest(document, source, delivery = { placement:
 export function derivePageManifest(sourceFile, productComponents = [], source, delivery) {
     return derivePageManifestFromDocument(readFileSync(sourceFile, 'utf8'), productComponents, source, delivery);
 }
-/** Read and validate page.json from a ticket directory. */
-export function parsePage(dir) {
-    let raw;
+function readPageJson(dir) {
     try {
-        raw = JSON.parse(readFileSync(join(dir, 'page.json'), 'utf8'));
+        return JSON.parse(readFileSync(join(dir, 'page.json'), 'utf8'));
     }
     catch {
         throw new PageAuthoringError('page.json is not valid JSON');
     }
-    return validatePageManifest(raw);
+}
+/** Read and validate page.json from a ticket directory. */
+export function parsePage(dir) {
+    return validatePageManifest(readPageJson(dir));
+}
+/** Read only the stable delivery envelope without interpreting component config. */
+export function parsePageDelivery(dir) {
+    const raw = readPageJson(dir);
+    const parsed = pageDeliverySchema.safeParse(typeof raw === 'object' && raw !== null && !Array.isArray(raw)
+        ? raw['delivery']
+        : undefined);
+    if (!parsed.success)
+        throw new PageAuthoringError('page.json has an invalid delivery envelope');
+    return parsed.data;
 }

package/dist/core/human/scan.d.ts

@@ -3,8 +3,9 @@ import type { PageTicketSummary, TicketSummary } from './types.js';
 export declare function scanInbox(): TicketSummary[];
 export type PageHistoryEntry = PageTicketSummary;
 /**
- * Every page ticket raised by one node — pending, resolved or canceled — oldest
- * first. This is the durable discovery seam for transcript placement, so it is a
- * separate walk from the pending-only inbox scan and never filters on a terminal file.
+ * Every page ticket — pending, resolved or canceled — oldest first, optionally
+ * narrowed to one raising node. This is the durable discovery seam for
+ * transcript placement and for browsing settled tickets, so it is a separate
+ * walk from the pending-only inbox scan and never filters on a terminal file.
  */
-export declare function scanPageHistory(nodeId: string): PageHistoryEntry[];
+export declare function scanPageHistory(nodeId?: string): PageHistoryEntry[];

package/dist/core/human/scan.js

@@ -94,9 +94,10 @@ export function scanInbox() {
     return items.sort((a, b) => (b.kind === 'page' ? b.emittedAt : b.blockedSince).localeCompare(a.kind === 'page' ? a.emittedAt : a.blockedSince) || a.id.localeCompare(b.id));
 }
 /**
- * Every page ticket raised by one node — pending, resolved or canceled — oldest
- * first. This is the durable discovery seam for transcript placement, so it is a
- * separate walk from the pending-only inbox scan and never filters on a terminal file.
+ * Every page ticket — pending, resolved or canceled — oldest first, optionally
+ * narrowed to one raising node. This is the durable discovery seam for
+ * transcript placement and for browsing settled tickets, so it is a separate
+ * walk from the pending-only inbox scan and never filters on a terminal file.
  */
 export function scanPageHistory(nodeId) {
     let entries;
@@ -117,7 +118,9 @@ export function scanPageHistory(nodeId) {
             continue;
         }
         const summary = pageSummary(dir, basename(dir));
-        if (summary === null || summary.source.nodeId !== nodeId)
+        if (summary === null)
+            continue;
+        if (nodeId !== undefined && summary.source.nodeId !== nodeId)
             continue;
         const result = summary.state === 'resolved' ? readTicketResult(dir) : null;
         items.push({ ...summary, ...(result?.kind === 'page' ? { answerDigest: result.summary.replace(/\s+/g, ' ').trim() } : {}) });

package/dist/core/human/tickets.js

@@ -5,7 +5,7 @@ import { z } from 'zod';
 import { buildPageSummary } from './summary.js';
 import { atomicWriteJson, atomicWriteText, clearProgress, claimPath, pageManifestPath, pageModulePath, pagePath, progressPath, publishJsonExclusive, requireTicket, responsePath, reviewPath } from './convention.js';
 import { validateReviewDescriptor, validateReviewProjection } from './review-schema.js';
-import { compilePage, deriveHtmlPageManifest, derivePageManifestFromDocument, parsePage, PageAuthoringError } from './page.js';
+import { compilePage, deriveHtmlPageManifest, derivePageManifestFromDocument, parsePage, parsePageDelivery, PageAuthoringError } from './page.js';
 import { isResponseBearingSlot, validatePageResponses, validatePartialPageResponses } from './page-schema.js';
 import { signalInboxActivity } from './root.js';
 import { readTicketClaim, releaseClaimLocked, withTicketLock } from './claim.js';
@@ -145,6 +145,13 @@ function requireSettleablePage(dir) {
         throw new Error('page_has_no_response_lifecycle');
     return manifest;
 }
+function requireCancelablePage(dir) {
+    // Cancellation never interprets answers. Reading only this stable envelope
+    // keeps an older resident daemon able to retract a page authored by a newer CLI.
+    const delivery = parsePageDelivery(dir);
+    if (!delivery.inbox && !delivery.reply)
+        throw new Error('page_has_no_response_lifecycle');
+}
 function isEmptyResponseMap(responses) {
     return typeof responses === 'object' && responses !== null && !Array.isArray(responses) && Object.keys(responses).length === 0;
 }
@@ -272,7 +279,7 @@ export function cancelTicket(dir, opts = {}) {
     const ticket = requireTicket(dir);
     const canceled = withTicketLock(ticket, () => {
         if (existsSync(pageManifestPath(ticket)))
-            requireSettleablePage(ticket);
+            requireCancelablePage(ticket);
         const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: new Date().toISOString(), ...(opts.reason === undefined ? {} : { reason: opts.reason }), ...(opts.actor === undefined ? {} : { actor: opts.actor }) };
         const won = exclusiveResult(ticket, result);
         return { status: won ? 'canceled' : 'already_resolved', result: won ? result : readTicketResult(ticket) ?? result };

package/dist/core/io.js

@@ -6,6 +6,7 @@
 import { renameSync, writeFileSync } from 'node:fs';
 import { CrtrError } from './errors.js';
 import { ExitCode } from '../types.js';
+import { PREVIEW_RESULT_PATH_ENV } from './preview-result-path.js';
 import { renderError } from './render.js';
 import { ApiError } from '../api/index.js';
 // ---------------------------------------------------------------------------
@@ -16,11 +17,11 @@ let preview;
 /** Begin collecting the current leaf's structured response, if its caller
  * supplied the private per-tool-call result path. */
 export function beginPreview(path) {
-    const resultPath = process.env['CRTR_PREVIEW_RESULT_PATH'];
+    const resultPath = process.env[PREVIEW_RESULT_PATH_ENV];
     preview = resultPath === undefined || resultPath === '' ? undefined : { path, jsonl: [] };
 }
 function publishPreview(record) {
-    const resultPath = process.env['CRTR_PREVIEW_RESULT_PATH'];
+    const resultPath = process.env[PREVIEW_RESULT_PATH_ENV];
     if (resultPath === undefined || resultPath === '')
         return;
     const tempPath = `${resultPath}.${process.pid}.tmp`;

package/dist/core/manifest.d.ts

@@ -2,4 +2,6 @@ import type { MarketplaceManifest, PluginManifest } from '../types.js';
 export declare function pluginManifestPath(pluginRoot: string): string;
 export declare function marketplaceManifestPath(mktRoot: string): string;
 export declare function readPluginManifest(pluginRoot: string): PluginManifest | null;
+/** Validate an optional memory-extension declaration at package preflight. */
+export declare function validatePluginManifestMemoryExtensions(manifest: PluginManifest): void;
 export declare function readMarketplaceManifest(mktRoot: string): MarketplaceManifest | null;

package/dist/core/manifest.js

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { MARKETPLACE_MANIFEST_DIR, MARKETPLACE_MANIFEST_FILE, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE, } from '../types.js';
+import { validatePluginMemoryExtensions } from './memory/extensions.js';
 import { readJsonIfExists } from './fs-utils.js';
 export function pluginManifestPath(pluginRoot) {
     return join(pluginRoot, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE);
@@ -10,6 +11,10 @@ export function marketplaceManifestPath(mktRoot) {
 export function readPluginManifest(pluginRoot) {
     return readJsonIfExists(pluginManifestPath(pluginRoot));
 }
+/** Validate an optional memory-extension declaration at package preflight. */
+export function validatePluginManifestMemoryExtensions(manifest) {
+    validatePluginMemoryExtensions(manifest);
+}
 export function readMarketplaceManifest(mktRoot) {
     return readJsonIfExists(marketplaceManifestPath(mktRoot));
 }

package/dist/core/memory/extensions.d.ts

@@ -0,0 +1,30 @@
+import type { MemoryExtensionDeclarations, MemoryExtensionScalar, PluginManifest } from '../../types.js';
+import type { MemoryDoc } from '../memory-resolver.js';
+export type MemoryExtensionCatalog = Record<string, MemoryExtensionDeclarations>;
+export interface MemoryExtensionValidationIssue {
+    path: string;
+    message: string;
+}
+export interface MemoryExtensionCatalogOptions {
+    /** The manifest currently being staged. Its namespace shadows an installed copy only for that candidate validation. */
+    candidate?: Pick<PluginManifest, 'name' | 'memory_extensions'>;
+}
+export declare function isMemoryExtensionScalar(value: unknown): value is MemoryExtensionScalar;
+/** Parse the closed declaration addendum. Callers that accept a plugin manifest
+ * invoke this at their install/preflight boundary; normal runtime catalogs only
+ * admit declarations which have already cleared that boundary. */
+export declare function validateMemoryExtensionDeclarations(raw: unknown): MemoryExtensionDeclarations;
+/** Throw when a manifest carries an invalid addendum; absent is valid. */
+export declare function validatePluginMemoryExtensions(manifest: Pick<PluginManifest, 'memory_extensions'>): void;
+/** Installed declarations used for validation and authoring. Disabled plugins
+ * remain present so existing values can still be checked and edited. */
+export declare function memoryExtensionValidationCatalog(doc: Pick<MemoryDoc, 'scope' | 'path'>, options?: MemoryExtensionCatalogOptions): MemoryExtensionCatalog;
+/** Winning enabled declarations used only to interpret structured output. */
+export declare function memoryExtensionEffectiveCatalog(doc: Pick<MemoryDoc, 'scope' | 'path'>): MemoryExtensionCatalog;
+/** Validate the raw `extensions` frontmatter value. Unresolved namespaces are
+ * intentionally reported rather than discarded: removal leaves raw metadata
+ * intact but lint-invalid until its plugin returns. */
+export declare function validateMemoryExtensionValues(raw: unknown, catalog: MemoryExtensionCatalog): MemoryExtensionValidationIssue[];
+/** Effective plugin metadata for structured consumers. It overlays only valid
+ * explicit scalars onto defaults and never mutates or serializes frontmatter. */
+export declare function projectEffectiveMemoryExtensions(raw: unknown, catalog: MemoryExtensionCatalog): Record<string, Record<string, MemoryExtensionScalar>>;