@north-light/crouter 0.3.191 → 0.3.193

package/dist/core/human/__tests__/serial/inbox-core.test.js

@@ -3,19 +3,29 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync,
 import { spawn } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { submitDeck, submitReview, completeDeck, cancelTicket, readTicketResult } from '../../tickets.js';
+import { submitPage, submitReview, completePage, cancelTicket, readTicketResult } from '../../tickets.js';
 import { claimTicket } from '../../claim.js';
 import { scanInbox } from '../../scan.js';
 import { atomicWriteJson, progressPath, responsePath } from '../../convention.js';
-import { validateDeck } from '../../deck-schema.js';
 import { ticketDir } from '../../root.js';
 const temp = mkdtempSync(join(tmpdir(), 'crtr-inbox-core-'));
 process.env['CRTR_HOME'] = temp;
 const source = join(temp, 'source.md');
 writeFileSync(source, '# Source\n');
-const deck = (blockedSince) => ({ title: 'A deck', source: { blockedSince, nodeId: 'node-1' }, interactions: [{ id: 'go', title: 'Go?', subtitle: 'Go? requires your attention.', options: [{ id: 'yes', label: 'Yes' }] }] });
-assert.throws(() => validateDeck({ interactions: [{ id: 'go', title: 'Go?', subtitle: 'Go? requires your attention.', options: [] }] }), /title/, 'a deck must carry its own explicit inbox title');
-assert.throws(() => validateDeck({ title: 'Missing subtitle', interactions: [{ id: 'go', title: 'Go?', options: [] }] }), /subtitle/, 'a deck interaction without an authored subtitle is invalid');
+const pageSource = join(temp, 'page.md');
+writeFileSync(pageSource, [
+    '---',
+    'title: A page',
+    'subtitle: Go? requires your attention.',
+    '---',
+    '',
+    '```slot:text',
+    '{ "id": "go", "initialText": "", "editable": true }',
+    '```',
+    '',
+].join('\n'));
+const page = (id, blockedSince) => submitPage({ dir: ticketDir(id), sourceFile: pageSource, dialect: 'md', source: { blockedSince, nodeId: 'node-1' } });
+const answer = { go: { text: 'yes', edited: true, comments: [] } };
 async function waitFor(paths) {
     for (let attempts = 0; !paths.every(existsSync); attempts++) {
         if (attempts > 1_000)
@@ -23,60 +33,60 @@ async function waitFor(paths) {
         await new Promise((resolvePromise) => setTimeout(resolvePromise, 1));
     }
 }
-const oldDeck = submitDeck({ dir: ticketDir('z-last'), deck: deck('2025-01-01T00:00:00.000Z') });
-const newDeck = submitDeck({ dir: ticketDir('a-first'), deck: deck('2025-01-02T00:00:00.000Z') });
+page('z-last', '2025-01-01T00:00:00.000Z');
+const newPage = page('a-first', '2025-01-02T00:00:00.000Z');
 const review = submitReview({ dir: ticketDir('review'), review: { file: source, title: 'Review source', subtitle: 'Review findings require your decision.', source: { nodeId: 'node-1' }, blockedSince: '2025-01-02T00:00:00.000Z' } });
 assert.throws(() => submitReview({ dir: ticketDir('missing-review-subtitle'), review: { file: source, title: 'Missing subtitle', source: {} } }), /subtitle/, 'a review without an authored subtitle is invalid');
 assert.throws(() => submitReview({ dir: ticketDir('bad-review'), review: { file: join(temp, 'missing.md'), title: 'Bad', subtitle: 'This invalid review must be rejected.', source: {} } }), /existing absolute path/);
 assert.equal(existsSync(ticketDir('bad-review')), false, 'invalid submission does not strand an id');
 const prepared = ticketDir('prepared');
 mkdirSync(prepared);
-writeFileSync(join(prepared, 'body.md'), 'prepared body');
-const preparedTicket = submitDeck({ dir: prepared, deck: { ...deck('2025-01-02T00:00:00.000Z'), interactions: [{ id: 'go', title: 'Go?', subtitle: 'Go? requires your attention.', bodyPath: 'body.md', options: [{ id: 'yes', label: 'Yes' }] }] } });
+writeFileSync(join(prepared, 'asset.png'), 'prepared asset');
+const preparedTicket = submitPage({ dir: prepared, sourceFile: pageSource, dialect: 'md', source: { blockedSince: '2025-01-02T00:00:00.000Z', nodeId: 'node-1' } });
 assert.equal(preparedTicket.dir, realpathSync(prepared), 'submission accepts a crouter-precreated direct child and colocated assets');
 // Same timestamp is stable by id; progress is resumable work, never a hidden lease.
-atomicWriteJson(progressPath(newDeck.dir), { kind: 'deck', responses: [], savedAt: new Date().toISOString() });
+atomicWriteJson(progressPath(newPage.dir), { kind: 'page', responses: {}, savedAt: new Date().toISOString() });
 const scanned = scanInbox();
 assert.deepEqual(scanned.map((item) => item.id), ['a-first', 'prepared', 'review', 'z-last']);
 assert.equal(scanned.find((item) => item.id === 'a-first')?.claim, undefined);
 assert.equal(scanned.find((item) => item.id === 'review')?.kind, 'review');
 assert.equal(scanned.find((item) => item.id === 'review')?.subtitle, 'Review findings require your decision.', 'review scanning exposes its required subtitle');
-const firstClaim = claimTicket(newDeck.dir);
+const firstClaim = claimTicket(newPage.dir);
 assert.notEqual(firstClaim, null);
-assert.equal(claimTicket(newDeck.dir), null, 'a second controller cannot claim a live ticket');
+assert.equal(claimTicket(newPage.dir), null, 'a second controller cannot claim a live ticket');
 // A separate process writes a genuine remote claim whose heartbeat is already
 // stale, then exits; this process recovers it — cross-process stale recovery.
-const staleDir = submitDeck({ dir: ticketDir('stale'), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+const staleDir = page('stale', '2025-01-03T00:00:00.000Z').dir;
 const staleClaimReady = join(temp, 'stale-claim-ready');
 await new Promise((resolveWorker, rejectWorker) => spawn(process.execPath, ['--conditions=crtr-src', '--import', 'tsx', 'src/core/human/__tests__/inbox-stale-claim-worker.ts', staleDir, staleClaimReady], { cwd: process.cwd(), stdio: ['ignore', 'ignore', 'inherit'] }).once('exit', (code) => code === 0 ? resolveWorker() : rejectWorker(new Error('stale-claim worker failed'))));
 assert.notEqual(JSON.parse(readFileSync(staleClaimReady, 'utf8')), null, 'a separate process wrote a stale remote claim on disk');
 assert.notEqual(claimTicket(staleDir), null, 'a remote claim written by another process recovers once its heartbeat has expired');
-const malformedDir = submitDeck({ dir: ticketDir('malformed-claim'), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+const malformedDir = page('malformed-claim', '2025-01-03T00:00:00.000Z').dir;
 writeFileSync(join(malformedDir, 'claim.json'), '{');
 assert.notEqual(claimTicket(malformedDir), null, 'partial claim crash artifact recovers');
-const final = completeDeck(newDeck.dir, [{ id: 'go', selectedOptionId: 'yes' }], firstClaim.token);
+const final = completePage(newPage.dir, answer, firstClaim.token);
 assert.equal(final.won, true);
-assert.equal(readTicketResult(newDeck.dir)?.kind, 'deck');
-assert.equal(claimTicket(newDeck.dir), null, 'terminal tickets cannot be claimed');
+assert.equal(readTicketResult(newPage.dir)?.kind, 'page');
+assert.equal(claimTicket(newPage.dir), null, 'terminal tickets cannot be claimed');
 const exactResults = [
-    { schema: 'humanloop.response/v2', kind: 'deck', responses: [], summary: '', completedAt: '2025-01-04T00:00:00.000Z' },
+    { schema: 'crtr.page-response/v1', kind: 'page', responses: {}, summary: '', completedAt: '2025-01-04T00:00:00.000Z' },
     { schema: 'humanloop.review-response/v1', kind: 'review', result: { file: source, submitted: true, approved: true, comments: [], submittedAt: '2025-01-04T00:00:00.000Z', savedAt: '2025-01-04T00:00:00.000Z', reviewId: 'review-1', changed: false, baselineSha256: 'baseline', approvedSha256: 'approved', companionNodeId: 'companion-1', commentsTotal: 0, commentsUnresolved: 0 }, completedAt: '2025-01-04T00:00:00.000Z' },
     { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: '2025-01-04T00:00:00.000Z', reason: 'stop', actor: 'test' },
 ];
 for (const [index, result] of exactResults.entries()) {
-    const dir = submitDeck({ dir: ticketDir(`strict-${index}`), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+    const dir = page(`strict-${index}`, '2025-01-03T00:00:00.000Z').dir;
     writeFileSync(responsePath(dir), JSON.stringify(result));
     assert.equal(readTicketResult(dir)?.kind, result.kind, `strict decoder accepts exact ${result.kind} result`);
 }
 const validFeedback = exactResults[1].result;
 const iso = '2025-01-04T00:00:00.000Z';
 const rejectFixtures = [
-    { why: 'a wrong kind for a known schema', result: { schema: 'humanloop.response/v2', kind: 'review', responses: [], summary: '', completedAt: iso } },
-    { why: 'an unknown schema id', result: { schema: 'humanloop.response/v9', kind: 'deck', responses: [], summary: '', completedAt: iso } },
-    { why: 'a deck missing its required completedAt', result: { schema: 'humanloop.response/v2', kind: 'deck', responses: [], summary: '' } },
-    { why: 'a deck with a non-ISO completedAt', result: { schema: 'humanloop.response/v2', kind: 'deck', responses: [], summary: '', completedAt: 'now' } },
-    { why: 'a deck with an unrecognized nested response field', result: { schema: 'humanloop.response/v2', kind: 'deck', responses: [{ id: 'go', bogus: true }], summary: '', completedAt: iso } },
-    { why: 'a deck with an extra top-level field', result: { schema: 'humanloop.response/v2', kind: 'deck', responses: [], summary: '', completedAt: iso, extra: true } },
+    { why: 'a wrong kind for a known schema', result: { schema: 'crtr.page-response/v1', kind: 'review', responses: {}, summary: '', completedAt: iso } },
+    { why: 'an unknown schema id', result: { schema: 'crtr.page-response/v9', kind: 'page', responses: {}, summary: '', completedAt: iso } },
+    { why: 'a page missing its required completedAt', result: { schema: 'crtr.page-response/v1', kind: 'page', responses: {}, summary: '' } },
+    { why: 'a page with a non-ISO completedAt', result: { schema: 'crtr.page-response/v1', kind: 'page', responses: {}, summary: '', completedAt: 'now' } },
+    { why: 'a page whose responses are not a slot-keyed map', result: { schema: 'crtr.page-response/v1', kind: 'page', responses: [{ id: 'go' }], summary: '', completedAt: iso } },
+    { why: 'a page with an extra top-level field', result: { schema: 'crtr.page-response/v1', kind: 'page', responses: {}, summary: '', completedAt: iso, extra: true } },
     { why: 'a review missing its required result', result: { schema: 'humanloop.review-response/v1', kind: 'review', completedAt: iso } },
     { why: 'a review whose nested result is not submitted', result: { schema: 'humanloop.review-response/v1', kind: 'review', result: { ...validFeedback, submitted: false }, completedAt: iso } },
     { why: 'a review with incomplete comment columns', result: { schema: 'humanloop.review-response/v1', kind: 'review', result: { ...validFeedback, approved: true, comments: [{ id: 'c1', line: 1, endLine: 1, colStart: 1, lineText: '# Source', comment: 'x', createdAt: iso }] }, completedAt: iso } },
@@ -87,29 +97,29 @@ const rejectFixtures = [
     { why: 'a canceled result with an extra top-level field', result: { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: iso, extra: true } },
 ];
 for (const [index, fixture] of rejectFixtures.entries()) {
-    const dir = submitDeck({ dir: ticketDir(`strict-reject-${index}`), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+    const dir = page(`strict-reject-${index}`, '2025-01-03T00:00:00.000Z').dir;
     writeFileSync(responsePath(dir), JSON.stringify(fixture.result));
     assert.equal(readTicketResult(dir), null, `strict decoder rejects ${fixture.why}`);
 }
 const protocolDir = ticketDir('stale-protocol');
 mkdirSync(protocolDir);
 writeFileSync(responsePath(protocolDir), '{}');
-assert.throws(() => submitDeck({ dir: protocolDir, deck: deck('2025-01-03T00:00:00.000Z') }), /protocol state/, 'precreated assets may not include humanloop lifecycle state');
-const cancelDir = submitDeck({ dir: ticketDir('cancel-race'), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+assert.throws(() => submitPage({ dir: protocolDir, sourceFile: pageSource, dialect: 'md' }), /protocol state/, 'precreated assets may not include humanloop lifecycle state');
+const cancelDir = page('cancel-race', '2025-01-03T00:00:00.000Z').dir;
 const canceled = cancelTicket(cancelDir, { reason: 'stop' });
 assert.equal(canceled.status, 'canceled');
 assert.equal(cancelTicket(cancelDir).status, 'already_resolved', 'first final writer wins');
-const finalRaceDir = submitDeck({ dir: ticketDir('final-race'), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+const finalRaceDir = page('final-race', '2025-01-03T00:00:00.000Z').dir;
 const finalRaceClaim = claimTicket(finalRaceDir);
 const finalBarrier = join(temp, 'final-race-barrier');
 const finalReady = join(temp, 'final-race-ready');
 const cancelWorker = spawn(process.execPath, ['--conditions=crtr-src', '--import', 'tsx', 'src/core/human/__tests__/inbox-cancel-worker.ts', finalRaceDir, finalBarrier, finalReady], { cwd: process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
 await waitFor([finalReady]);
 writeFileSync(finalBarrier, 'go');
-const finalRace = completeDeck(finalRaceDir, [{ id: 'go', selectedOptionId: 'yes' }], finalRaceClaim.token);
+const finalRace = completePage(finalRaceDir, answer, finalRaceClaim.token);
 await new Promise((resolveWorker, rejectWorker) => cancelWorker.once('exit', (code) => code === 0 ? resolveWorker() : rejectWorker(new Error('cancel worker failed'))));
-assert.equal(readTicketResult(finalRaceDir)?.kind, finalRace.won ? 'deck' : 'canceled', 'submit and cancellation race has one canonical winner');
-const concurrentDir = submitDeck({ dir: ticketDir('concurrent-claim'), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+assert.equal(readTicketResult(finalRaceDir)?.kind, finalRace.won ? 'page' : 'canceled', 'submit and cancellation race has one canonical winner');
+const concurrentDir = page('concurrent-claim', '2025-01-03T00:00:00.000Z').dir;
 const claimBarrier = join(temp, 'claim-race-barrier');
 // Both workers block on this release until the parent has read both results, so
 // neither winner's pid dies during the peer's attempt (a dead same-host pid is

package/dist/core/human/claim.js

@@ -1,7 +1,7 @@
 import { existsSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { randomUUID } from 'node:crypto';
-import { claimPath, deckPath, responsePath, reviewPath } from './convention.js';
+import { claimPath, pageManifestPath, responsePath, reviewPath } from './convention.js';
 import { readJsonOrNull } from '../fs-utils.js';
 import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 const REMOTE_STALE_MS = 30_000;
@@ -30,7 +30,7 @@ export function isStaleClaim(claim, now = Date.now(), localHost = hostname()) {
 /** Acquire a visible claim only for a still-pending ticket. Malformed crash artifacts are stale claims. */
 export function claimTicket(dir, opts = {}) {
     return withExclusiveDirectoryLock(`${dir}/.ticket-lock`, () => {
-        if (existsSync(responsePath(dir)) || (!existsSync(deckPath(dir)) && !existsSync(reviewPath(dir))))
+        if (existsSync(responsePath(dir)) || (!existsSync(pageManifestPath(dir)) && !existsSync(reviewPath(dir))))
             return null;
         const path = claimPath(dir);
         const existing = readTicketClaim(dir);

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

@@ -1,5 +1,7 @@
-import type { Deck, InteractionResponse } from './types.js';
-export declare function deckPath(dir: string): string;
+import type { PageManifest } from './page-schema.js';
+/** The authored page source, colocated with its derived manifest in the bridge node directory. */
+export declare function pagePath(dir: string, dialect: PageManifest['dialect']): string;
+export declare function pageManifestPath(dir: string): string;
 export declare function reviewPath(dir: string): string;
 export declare function responsePath(dir: string): string;
 export declare function progressPath(dir: string): string;
@@ -13,6 +15,4 @@ export declare function requireTicket(dir: string): string;
 export declare function atomicWriteJson(path: string, value: unknown): void;
 /** Publish one immutable JSON record without replacing an existing winner. */
 export declare function publishJsonExclusive(path: string, value: unknown): boolean;
-export declare function writeResponse(dir: string, responses: InteractionResponse[], completedAt: string, deck?: Deck): string;
-export declare function writeProgress(dir: string, responses: InteractionResponse[]): void;
 export declare function clearProgress(dir: string): void;

package/dist/core/human/convention.js

@@ -1,13 +1,14 @@
 import { existsSync, linkSync, mkdirSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { buildSummary } from './summary.js';
-export function deckPath(dir) { return `${dir}/deck.json`; }
+/** The authored page source, colocated with its derived manifest in the bridge node directory. */
+export function pagePath(dir, dialect) { return `${dir}/page.${dialect}`; }
+export function pageManifestPath(dir) { return `${dir}/page.json`; }
 export function reviewPath(dir) { return `${dir}/review.json`; }
 export function responsePath(dir) { return `${dir}/response.json`; }
 export function progressPath(dir) { return `${dir}/progress.json`; }
 export function claimPath(dir) { return `${dir}/claim.json`; }
 export function interactionState(dir) {
-    if (!existsSync(deckPath(dir)) && !existsSync(reviewPath(dir)))
+    if (!existsSync(pageManifestPath(dir)) && !existsSync(reviewPath(dir)))
         return 'missing';
     if (existsSync(responsePath(dir)))
         return 'resolved';
@@ -18,8 +19,8 @@ export function isClaimed(dir) { return existsSync(claimPath(dir)); }
 /** Resolve and verify a ticket directory without a registry. */
 export function requireTicket(dir) {
     const canonicalDir = realpathSync(dir);
-    if (!existsSync(deckPath(canonicalDir)) && !existsSync(reviewPath(canonicalDir))) {
-        throw new Error('ticket directory has no deck or review');
+    if (!existsSync(pageManifestPath(canonicalDir)) && !existsSync(reviewPath(canonicalDir))) {
+        throw new Error('ticket directory has no page or review');
     }
     return canonicalDir;
 }
@@ -47,14 +48,6 @@ export function publishJsonExclusive(path, value) {
         unlinkSync(tmp);
     }
 }
-export function writeResponse(dir, responses, completedAt, deck) {
-    const summary = deck === undefined ? '' : buildSummary(deck, responses);
-    atomicWriteJson(responsePath(dir), { schema: 'humanloop.response/v2', kind: 'deck', responses, summary, completedAt });
-    return responsePath(dir);
-}
-export function writeProgress(dir, responses) {
-    atomicWriteJson(progressPath(dir), { kind: 'deck', responses, savedAt: new Date().toISOString() });
-}
 export function clearProgress(dir) {
     try {
         unlinkSync(progressPath(dir));

package/dist/core/human/markdown-html.d.ts

@@ -0,0 +1,8 @@
+/** Escape text for an HTML text node. */
+export declare function escapeHtmlText(raw: string): string;
+/** Escape a value for a double-quoted HTML attribute. */
+export declare function escapeHtmlAttribute(raw: string): string;
+/** Render one markdown document fragment as HTML. */
+export declare function renderMarkdownToHtml(markdown: string): string;
+/** Render inline markdown. Exported for callers rendering a single line. */
+export declare function renderInline(source: string): string;