@astrosheep/square 0.3.10 → 0.3.12

package/dist/artifact.js

@@ -1,674 +1,393 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
-import { ACTIVITIES_HEADING, ACTIVITIES_MARKER, ACT_MARKER_PREFIX, WARMUP_HEADING, WARMUP_MARKER, SquareError, CURRENT_FORMAT_VERSION, formatHardCap, sameName, } from './model.js';
-import { formatTimestamp, parseTimestamp } from './time.js';
-const V2_KINDS = new Set(['say', 'join', 'done', 'hold', 'resume']);
-export function quoteBody(body) {
-    const normalized = body.replace(/\r\n/g, '\n').trim();
-    if (normalized === '')
-        return '>';
-    return normalized
-        .split('\n')
-        .map((line) => (line === '' ? '>' : `> ${line}`))
-        .join('\n');
-}
-export function unquoteBody(lines) {
-    const out = [...lines];
-    while (out.length > 0 && out[0] === '')
-        out.shift();
-    while (out.length > 0 && out[out.length - 1] === '')
-        out.pop();
-    return out
-        .map((line) => {
-        if (line === '>')
-            return '';
-        if (line.startsWith('> '))
-            return line.slice(2);
-        if (line.startsWith('>'))
-            return line.slice(1);
-        return line;
-    })
-        .join('\n')
-        .trim();
-}
-function actIndex(act) {
-    if (act.index === undefined || !Number.isInteger(act.index) || act.index < 0) {
-        throw new SquareError('invalid_args', `Invalid square act: missing stable index for ${act.kind}.`);
-    }
-    return act.index;
-}
-function renderActMarker(act) {
-    const marker = {
-        index: actIndex(act),
-        kind: act.kind,
-        actor: act.actor,
-        at: act.at,
-        ...(act.kind === 'say' && act.reach !== undefined ? { reach: act.reach } : {}),
-        ...(act.kind === 'say' && act.reply !== undefined ? { reply: act.reply } : {}),
-    };
-    return `${ACT_MARKER_PREFIX} ${JSON.stringify(marker)} -->`;
-}
-function actNeedsBody(act) {
-    return act.kind === 'say' || act.kind === 'done' || act.kind === 'hold';
-}
-export function renderArtifactAct(act, opts = {}) {
-    const head = opts.first ? '' : '\n';
-    const out = [`${head}${renderActMarker(act)}`, `### ${act.actor}`, `_${act.kind} · ${formatTimestamp(act.at)}_`];
-    if (actNeedsBody(act))
-        out.push('', quoteBody('body' in act ? act.body ?? '' : ''));
-    return out.join('\n');
+import path from 'node:path';
+import { TextDecoder } from 'node:util';
+import zlib from 'node:zlib';
+import { isWakeRouteKind, nameKey, SquareError, } from './model.js';
+import { parseActivityId } from './square-core.js';
+const SQUARE_MAGIC = Buffer.from('SQUARE01', 'ascii');
+const ARCHIVE_MAGIC = Buffer.from('SQARCH01', 'ascii');
+const LENGTH_BYTES = 4;
+const DIGEST_BYTES = 32;
+const HEADER_BYTES = SQUARE_MAGIC.length + LENGTH_BYTES + DIGEST_BYTES;
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+function invalidArtifact(detail) {
+    return new SquareError('invalid_args', `Invalid square artifact: ${detail}`);
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-export function emptyRuntimeState(nextActIndex = 0) {
-    return {
-        version: 2,
-        nextActIndex,
-        cursors: {},
-        deliveryReceipts: {},
-        leases: {},
-    };
+function hasExactKeys(value, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    return required.every((key) => Object.hasOwn(value, key))
+        && Object.keys(value).every((key) => allowed.has(key));
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isNonblankString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function validateReadCursor(value) {
+    return isObject(value)
+        && hasExactKeys(value, ['consumedThroughIndex', 'updatedAt'])
+        && Number.isSafeInteger(value.consumedThroughIndex)
+        && value.consumedThroughIndex >= -1
+        && isFiniteNumber(value.updatedAt);
+}
+function validateDeliveryReceipt(value) {
+    return isObject(value)
+        && hasExactKeys(value, ['status', 'at'])
+        && value.status === 'delivered'
+        && isFiniteNumber(value.at);
+}
+function validateWatchLease(value) {
+    if (!isObject(value)
+        || !hasExactKeys(value, ['leaseId', 'heartbeatAt', 'expiresAt'], ['ownerId', 'filter'])
+        || !isNonblankString(value.leaseId)
+        || (value.ownerId !== undefined && !isNonblankString(value.ownerId))
+        || !isFiniteNumber(value.heartbeatAt)
+        || !isFiniteNumber(value.expiresAt)
+        || value.expiresAt < value.heartbeatAt)
+        return false;
+    if (value.filter === undefined)
+        return true;
+    return isObject(value.filter)
+        && hasExactKeys(value.filter, [], ['participants', 'mention'])
+        && (value.filter.participants === undefined || isStringArray(value.filter.participants))
+        && (value.filter.mention === undefined || typeof value.filter.mention === 'string');
+}
+function validateNotifyLease(value) {
+    if (!isObject(value)
+        || !hasExactKeys(value, ['leaseId', 'expiresAt', 'phase'], ['attemptN', 'routeKind'])
+        || !isNonblankString(value.leaseId)
+        || !isFiniteNumber(value.expiresAt)
+        || (value.phase !== 'claimed' && value.phase !== 'dispatching')
+        || (value.attemptN !== undefined && (!Number.isSafeInteger(value.attemptN) || value.attemptN <= 0))
+        || (value.routeKind !== undefined && !isWakeRouteKind(value.routeKind)))
+        return false;
+    return value.phase !== 'dispatching' || (value.attemptN !== undefined && value.routeKind !== undefined);
 }
-function renderFrontmatter(doc) {
-    return [
-        '---',
-        `hard_cap: ${formatHardCap(doc.hardCap)}`,
-        ...(doc.throttlePerMinute === undefined ? [] : [`throttle_per_minute: ${doc.throttlePerMinute}`]),
-        `format_version: ${CURRENT_FORMAT_VERSION}`,
-        '---',
-    ].join('\n');
-}
-export function renderSquare(opts, snippet) {
-    const templateFile = opts.template
-        ? new URL(`../templates/${opts.template}.md`, import.meta.url)
-        : new URL('../template.md', import.meta.url);
-    const template = fs.readFileSync(templateFile, 'utf8');
-    const body = template.replace(/^---\n[\s\S]*?\n---\n?/, '').trimStart();
-    const genericGuide = fs.readFileSync(new URL('../guides/participant.md', import.meta.url), 'utf8').trim();
-    let templateGuide = '';
-    if (opts.template) {
-        try {
-            templateGuide = '\n\n' + fs.readFileSync(new URL(`../guides/${opts.template}.md`, import.meta.url), 'utf8').trim();
-        }
-        catch {
-            // No template-specific guide.
-        }
-    }
-    const training = [
-        '---',
-        '',
-        WARMUP_HEADING,
-        WARMUP_MARKER,
-        '',
-        genericGuide + templateGuide,
-        '',
-    ].join('\n');
-    const normalizedSnippet = snippet.replace(/\r\n/g, '\n').trim();
-    return [
-        renderFrontmatter({
-            hardCap: opts.hardCap,
-            throttlePerMinute: opts.throttlePerMinute,
-        }),
-        '',
-        normalizedSnippet,
-        '',
-        training,
-        body,
-    ].join('\n');
-}
-function sidecarPath(squarePath) {
-    return `${squarePath}.runtime.json`;
-}
-function invalidRuntimeSidecar(squarePath, detail) {
-    return new SquareError('invalid_args', `Invalid square runtime sidecar ${sidecarPath(squarePath)}: ${detail}`);
-}
-function validateRuntimeSidecar(squarePath, value) {
-    if (!isObject(value))
-        throw invalidRuntimeSidecar(squarePath, 'expected a JSON object.');
-    if (value.version !== 2)
-        throw invalidRuntimeSidecar(squarePath, 'unsupported or missing version.');
-    if (typeof value.nextActIndex !== 'number' || !Number.isInteger(value.nextActIndex) || value.nextActIndex < 0) {
-        throw invalidRuntimeSidecar(squarePath, 'nextActIndex must be a non-negative integer.');
-    }
-    if (!isObject(value.cursors) || !Object.values(value.cursors).every(isReadCursor)) {
-        throw invalidRuntimeSidecar(squarePath, 'cursors contains an invalid read cursor.');
-    }
-    if (!isObject(value.deliveryReceipts) || !Object.values(value.deliveryReceipts).every(isDeliveryReceiptMap)) {
-        throw invalidRuntimeSidecar(squarePath, 'deliveryReceipts contains an invalid receipt map.');
-    }
-    if (!isObject(value.leases) || !Object.values(value.leases).every(isWatchLease)) {
-        throw invalidRuntimeSidecar(squarePath, 'leases contains an invalid watch lease.');
-    }
-    return {
-        version: 2,
-        nextActIndex: value.nextActIndex,
-        cursors: value.cursors,
-        deliveryReceipts: value.deliveryReceipts,
-        leases: value.leases,
-    };
+function validateRecord(value, item) {
+    return isObject(value)
+        && Object.entries(value).every(([key, candidate]) => key.length > 0 && item(candidate));
 }
-export function loadRuntimeSidecar(squarePath, fallbackRuntime) {
-    const sp = sidecarPath(squarePath);
+function parseNotifyLeaseKey(key) {
+    let parsed;
     try {
-        const raw = fs.readFileSync(sp, 'utf8');
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            throw invalidRuntimeSidecar(squarePath, 'malformed JSON.');
-        }
-        return validateRuntimeSidecar(squarePath, parsed);
+        parsed = JSON.parse(key);
     }
-    catch (err) {
-        if (err.code === 'ENOENT') {
-            return fallbackRuntime;
-        }
-        throw err;
+    catch {
+        return undefined;
     }
-}
-export function mergeRuntimeState(markdownRuntime, sidecarRuntime) {
-    return {
-        ...sidecarRuntime,
-        nextActIndex: Math.max(markdownRuntime.nextActIndex, sidecarRuntime.nextActIndex),
-    };
-}
-export function saveRuntimeSidecar(squarePath, runtime) {
-    const target = sidecarPath(squarePath);
-    const normalized = validateRuntimeSidecar(squarePath, runtime);
-    const temporary = `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-    try {
-        fs.writeFileSync(temporary, JSON.stringify(normalized, null, 2));
-        fs.renameSync(temporary, target);
+    if (!Array.isArray(parsed) || parsed.length !== 2)
+        return undefined;
+    const [id, name] = parsed;
+    if (typeof id !== 'string' || typeof name !== 'string' || name.length === 0 || nameKey(name) !== name) {
+        return undefined;
     }
-    catch (error) {
-        try {
-            fs.unlinkSync(temporary);
+    const index = parseActivityId(id);
+    if (index === undefined)
+        return undefined;
+    if (JSON.stringify([id, name]) !== key)
+        return undefined;
+    return { index, name };
+}
+function validateRuntime(value) {
+    if (!isObject(value)
+        || !hasExactKeys(value, ['nextActIndex', 'cursors', 'deliveryReceipts', 'leases', 'notifyLeases'])
+        || !isNonNegativeInteger(value.nextActIndex)
+        || !validateRecord(value.cursors, validateReadCursor)
+        || !validateRecord(value.leases, validateWatchLease)
+        || !validateRecord(value.notifyLeases, validateNotifyLease)
+        || !isObject(value.deliveryReceipts))
+        return false;
+    return Object.entries(value.deliveryReceipts).every(([name, receipts]) => name.length > 0
+        && isObject(receipts)
+        && Object.entries(receipts).every(([id, receipt]) => parseActivityId(id) !== undefined && validateDeliveryReceipt(receipt)));
+}
+function validateAssignedRuntimeReferences(runtime) {
+    const bound = runtime.nextActIndex;
+    for (const cursor of Object.values(runtime.cursors)) {
+        if (cursor.consumedThroughIndex !== -1 && cursor.consumedThroughIndex >= bound)
+            return 'future';
+    }
+    for (const receipts of Object.values(runtime.deliveryReceipts)) {
+        for (const id of Object.keys(receipts)) {
+            const index = parseActivityId(id);
+            if (index === undefined)
+                return 'malformed';
+            if (index >= bound)
+                return 'future';
         }
-        catch { }
-        throw error;
     }
+    for (const key of Object.keys(runtime.notifyLeases)) {
+        const parsed = parseNotifyLeaseKey(key);
+        if (parsed === undefined)
+            return 'malformed';
+        if (parsed.index >= bound)
+            return 'future';
+    }
+    return 'ok';
 }
-export function renderSquareDoc(doc) {
-    const warmup = renderWarmupSection(doc.warmup);
-    return [
-        renderFrontmatter({ hardCap: doc.hardCap, throttlePerMinute: doc.throttlePerMinute }),
-        '',
-        ...doc.preamble,
-        ...(doc.preamble.length > 0 ? [''] : []),
-        ...warmup,
-        '',
-        ACTIVITIES_HEADING,
-        ACTIVITIES_MARKER,
-        ...(doc.acts.length === 0 ? [] : ['', doc.acts.map((act, index) => renderArtifactAct(act, { first: index === 0 })).join('\n')]),
-        '',
-    ].join('\n');
-}
-function renderWarmupSection(warmup) {
-    if (warmup[0]?.trim() === WARMUP_HEADING)
-        return [warmup[0], WARMUP_MARKER, ...warmup.slice(1)];
-    return [WARMUP_MARKER, ...warmup];
-}
-export function parsePreamble(text) {
-    const lines = text.split('\n');
-    const frontmatterEnd = lines.findIndex((line, index) => index > 0 && line === '---');
-    if (lines[0] !== '---' || frontmatterEnd < 0)
-        throw new SquareError('invalid_args', 'Invalid square: missing frontmatter.');
-    const marker = lines.findIndex((line) => line.trim() === WARMUP_MARKER);
-    if (marker < 0)
-        throw new SquareError('invalid_args', 'Invalid square: missing embedded warmup.');
-    const warmupStart = marker > 0 && lines[marker - 1].trim() === WARMUP_HEADING ? marker - 1 : marker;
-    const out = lines.slice(frontmatterEnd + 1, warmupStart);
-    trimBlankEdges(out);
-    return out;
-}
-function trimBlankEdges(lines) {
-    while (lines.length > 0 && lines[0] === '')
-        lines.shift();
-    while (lines.length > 0 && lines[lines.length - 1] === '')
-        lines.pop();
-}
-function parseFrontmatter(text) {
-    const match = text.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
-    if (!match)
-        throw new SquareError('invalid_args', 'Invalid square: missing frontmatter.');
-    return match[1];
-}
-export function isObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+function validateActor(value, required) {
+    return required ? isNonblankString(value) : value === undefined || isNonblankString(value);
 }
-export function isReadCursor(value) {
-    if (!isObject(value))
-        return false;
-    return (typeof value.consumedThroughIndex === 'number' &&
-        Number.isInteger(value.consumedThroughIndex) &&
-        value.consumedThroughIndex >= -1 &&
-        typeof value.updatedAt === 'number' &&
-        Number.isFinite(value.updatedAt));
-}
-export function isDeliveryReceipt(value) {
-    if (!isObject(value))
-        return false;
-    if (value.status !== 'delivered')
-        return false;
-    if (typeof value.at !== 'number' || !Number.isFinite(value.at))
+function validateStoredAct(value) {
+    if (!isObject(value)
+        || typeof value.kind !== 'string'
+        || !isNonNegativeInteger(value.index)
+        || !isFiniteNumber(value.at))
         return false;
-    if (value.reason !== undefined && value.reason !== 'reconciled')
-        return false;
-    if (value.actor !== undefined && (typeof value.actor !== 'string' || value.actor === ''))
-        return false;
-    if (value.reason === 'reconciled' && value.status !== 'delivered')
+    switch (value.kind) {
+        case 'join':
+            return hasExactKeys(value, ['kind', 'actor', 'at', 'index']) && validateActor(value.actor, true);
+        case 'done':
+            return hasExactKeys(value, ['kind', 'actor', 'at', 'index'], ['body'])
+                && validateActor(value.actor, true)
+                && (value.body === undefined || typeof value.body === 'string');
+        case 'say':
+            return hasExactKeys(value, ['kind', 'actor', 'at', 'body', 'index'], ['reach', 'reply'])
+                && validateActor(value.actor, true)
+                && typeof value.body === 'string'
+                && (value.reach === undefined || value.reach === 'bell')
+                && (value.reply === undefined || isNonNegativeInteger(value.reply));
+        case 'hold':
+            return hasExactKeys(value, ['kind', 'at', 'index'], ['actor', 'body'])
+                && validateActor(value.actor, false)
+                && (value.body === undefined || typeof value.body === 'string');
+        case 'resume':
+            return hasExactKeys(value, ['kind', 'at', 'index'], ['actor']) && validateActor(value.actor, false);
+        case 'read':
+            return hasExactKeys(value, ['kind', 'actor', 'at', 'through', 'index'])
+                && validateActor(value.actor, true)
+                && isNonNegativeInteger(value.through);
+        default:
+            return false;
+    }
+}
+function validateActs(value) {
+    if (!Array.isArray(value) || !value.every(validateStoredAct))
         return false;
+    let previous = -1;
+    for (const act of value) {
+        if (act.index <= previous)
+            return false;
+        if (act.kind === 'say' && act.reply !== undefined && act.reply >= act.index)
+            return false;
+        previous = act.index;
+    }
     return true;
 }
-export function isDeliveryReceiptMap(value) {
-    return isObject(value) && Object.entries(value).every(([id, receipt]) => /^act_\d+$/.test(id) && isDeliveryReceipt(receipt));
+function validateSquareDoc(value) {
+    if (!isObject(value)
+        || !hasExactKeys(value, ['hardCap', 'preamble', 'warmup', 'acts', 'runtime'], ['throttlePerMinute'])
+        || !(value.hardCap === null || (Number.isSafeInteger(value.hardCap) && value.hardCap > 0))
+        || (value.throttlePerMinute !== undefined
+            && (!Number.isSafeInteger(value.throttlePerMinute) || value.throttlePerMinute <= 0))
+        || !isStringArray(value.preamble)
+        || !isStringArray(value.warmup)
+        || !validateActs(value.acts)
+        || !validateRuntime(value.runtime)) {
+        throw invalidArtifact('snapshot schema is malformed.');
+    }
+    const acts = value.acts;
+    const runtime = value.runtime;
+    const historyBoundary = acts.at(-1)?.index ?? -1;
+    if (runtime.nextActIndex <= historyBoundary) {
+        throw invalidArtifact('nextActIndex is behind the activity history.');
+    }
+    const references = validateAssignedRuntimeReferences(runtime);
+    if (references === 'malformed')
+        throw invalidArtifact('snapshot schema is malformed.');
+    if (references === 'future')
+        throw invalidArtifact('runtime references an unassigned activity index.');
+    return value;
 }
-export function isWatchLease(value) {
-    if (!isObject(value))
-        return false;
-    if (typeof value.leaseId !== 'string' || value.leaseId === '')
-        return false;
-    if (value.ownerId !== undefined && (typeof value.ownerId !== 'string' || value.ownerId === ''))
-        return false;
-    if (typeof value.heartbeatAt !== 'number' || !Number.isFinite(value.heartbeatAt))
-        return false;
-    if (typeof value.expiresAt !== 'number' || !Number.isFinite(value.expiresAt))
-        return false;
-    if (value.expiresAt < value.heartbeatAt)
-        return false;
-    if (value.filter === undefined)
-        return true;
-    if (!isObject(value.filter))
-        return false;
-    const participants = value.filter.participants;
-    if (participants !== undefined && (!Array.isArray(participants) || !participants.every((item) => typeof item === 'string')))
-        return false;
-    const mention = value.filter.mention;
-    return mention === undefined || typeof mention === 'string';
-}
-function invalidVersionGuidance(reason) {
-    return new SquareError('invalid_args', `${reason} This format is no longer supported. Create a new square with \`square build\`.`);
-}
-function parseCap(text) {
-    const frontmatter = parseFrontmatter(text);
-    const match = frontmatter.match(/^hard_cap:\s*(-1|\d+)\s*$/m);
-    if (!match)
-        throw new SquareError('invalid_args', 'Invalid square: missing hard_cap in frontmatter. Expected a positive integer or -1.');
-    if (match[1] === '-1')
-        return null;
-    const hardCap = parseInt(match[1], 10);
-    if (hardCap <= 0)
-        throw new SquareError('invalid_args', 'Invalid square: hard_cap must be a positive integer or -1.');
-    return hardCap;
-}
-function parseThrottle(text) {
-    const frontmatter = parseFrontmatter(text);
-    const match = frontmatter.match(/^throttle_per_minute:\s*(\d+)\s*$/m);
-    if (!match)
-        return undefined;
-    const throttle = parseInt(match[1], 10);
-    if (throttle <= 0)
-        throw new SquareError('invalid_args', 'Invalid square: throttle_per_minute must be a positive integer.');
-    return throttle;
-}
-export function parseFormatVersion(text) {
-    const frontmatter = parseFrontmatter(text);
-    const match = frontmatter.match(/^format_version:\s*(\d+)\s*$/m);
-    if (!match) {
-        throw invalidVersionGuidance('Invalid square: missing format_version in frontmatter.');
+function encodeEnvelope(magic, value) {
+    const json = Buffer.from(JSON.stringify(value), 'utf8');
+    const payload = zlib.gzipSync(json, { level: 9 });
+    if (payload.length > 0xffff_ffff)
+        throw invalidArtifact('compressed payload is too large.');
+    const header = Buffer.alloc(HEADER_BYTES);
+    magic.copy(header, 0);
+    header.writeUInt32BE(payload.length, magic.length);
+    crypto.createHash('sha256').update(payload).digest().copy(header, magic.length + LENGTH_BYTES);
+    return Buffer.concat([header, payload]);
+}
+function decodeEnvelope(bytes, magic) {
+    if (bytes.length < HEADER_BYTES)
+        throw invalidArtifact('truncated header.');
+    if (!bytes.subarray(0, magic.length).equals(magic))
+        throw invalidArtifact('bad magic or unsupported format version.');
+    const length = bytes.readUInt32BE(magic.length);
+    if (bytes.length !== HEADER_BYTES + length)
+        throw invalidArtifact('payload length does not match the file.');
+    const expected = bytes.subarray(magic.length + LENGTH_BYTES, HEADER_BYTES);
+    const payload = bytes.subarray(HEADER_BYTES);
+    const actual = crypto.createHash('sha256').update(payload).digest();
+    if (!crypto.timingSafeEqual(expected, actual))
+        throw invalidArtifact('payload digest mismatch.');
+    let inflated;
+    try {
+        inflated = zlib.gunzipSync(payload);
     }
-    const version = parseInt(match[1], 10);
-    if (version !== CURRENT_FORMAT_VERSION) {
-        throw invalidVersionGuidance(`Invalid square: unsupported format_version ${version} (expected ${CURRENT_FORMAT_VERSION}).`);
+    catch {
+        throw invalidArtifact('payload is not valid gzip data.');
     }
-    return version;
-}
-export function parseSquare(text) {
-    parseFormatVersion(text);
-    const runtime = emptyRuntimeState(0);
-    const parsedActs = parseActs(text);
-    runtime.nextActIndex = parsedActs.nextActIndex;
-    return {
-        hardCap: parseCap(text),
-        throttlePerMinute: parseThrottle(text),
-        preamble: parsePreamble(text),
-        warmup: parseWarmup(text),
-        acts: parsedActs.acts,
-        runtime,
-    };
-}
-export function loadSquare(squarePath) {
     let text;
     try {
-        text = fs.readFileSync(squarePath, 'utf8');
+        text = utf8.decode(inflated);
     }
-    catch (err) {
-        if (err.code === 'ENOENT') {
-            throw new SquareError('not_found', `square file not found: ${squarePath}`);
-        }
-        throw err;
+    catch {
+        throw invalidArtifact('payload is not valid UTF-8.');
     }
-    const doc = parseSquare(text);
-    const markdownRuntime = doc.runtime;
-    const sidecar = loadRuntimeSidecar(squarePath, markdownRuntime);
-    // Markdown owns the activity history; runtime state owns delivery metadata.
-    // Preserve whichever history boundary is furthest ahead so a missing or
-    // stale sidecar can never cause an index to be reused.
-    doc.runtime = mergeRuntimeState(markdownRuntime, sidecar);
-    return doc;
-}
-function isSquareMarker(line) {
-    return /^<!-- square:(warmup|activities) -->$/.test(line.trim());
-}
-function findActivitiesMarker(lines, after = -1) {
-    return lines.findIndex((line, index) => index > after && line.trim() === ACTIVITIES_MARKER);
-}
-export function parseWarmup(text) {
-    const lines = text.split('\n');
-    const marker = lines.findIndex((line) => line.trim() === WARMUP_MARKER);
-    if (marker < 0)
-        throw new SquareError('invalid_args', 'Invalid square: missing embedded warmup.');
-    const start = marker > 0 && lines[marker - 1].trim() === WARMUP_HEADING ? marker - 1 : marker;
-    const endMarker = findActivitiesMarker(lines, start);
-    if (endMarker < 0)
-        throw new SquareError('invalid_args', 'Invalid square: missing ACTIVITIES section.');
-    const end = lines[endMarker].trim() === ACTIVITIES_MARKER && endMarker > 0 && lines[endMarker - 1].trim() === ACTIVITIES_HEADING
-        ? endMarker - 1
-        : endMarker;
-    const out = lines.slice(start, end).filter((line) => !isSquareMarker(line));
-    trimSection(out);
-    return out;
-}
-function parseReach(value) {
-    if (value === undefined)
-        return undefined;
-    if (value === 'bell')
-        return 'bell';
-    if (isObject(value) && typeof value.beside === 'string')
-        return { beside: value.beside };
-    throw new SquareError('invalid_args', 'Invalid square: malformed act reach metadata.');
-}
-export function parseActMarker(line) {
-    if (line === undefined || !line.startsWith(ACT_MARKER_PREFIX))
-        return null;
-    const match = line.match(/^<!-- square:act\s+(\{.*\})\s*-->$/);
-    if (!match)
-        return null;
-    let parsed;
     try {
-        parsed = JSON.parse(match[1]);
+        return JSON.parse(text);
     }
     catch {
-        throw new SquareError('invalid_args', 'Invalid square: malformed act marker JSON.');
-    }
-    if (!isObject(parsed))
-        throw new SquareError('invalid_args', 'Invalid square: act marker is missing index metadata.');
-    const index = parsed.index;
-    if (typeof index !== 'number' || !Number.isInteger(index) || index < 0) {
-        throw new SquareError('invalid_args', 'Invalid square: act marker is missing index metadata.');
+        throw invalidArtifact('payload is not valid JSON.');
     }
+}
+export function emptyRuntimeState(nextActIndex = 0) {
     return {
-        index,
-        ...(typeof parsed.kind === 'string' ? { kind: parsed.kind } : {}),
-        ...(typeof parsed.actor === 'string' ? { actor: parsed.actor } : {}),
-        ...(typeof parsed.at === 'number' && Number.isFinite(parsed.at) ? { at: parsed.at } : {}),
-        ...(parsed.reach !== undefined ? { reach: parseReach(parsed.reach) } : {}),
-        ...(parsed.reply !== undefined ? { reply: parseReply(parsed.reply) } : {}),
+        nextActIndex,
+        cursors: {},
+        deliveryReceipts: {},
+        leases: {},
+        notifyLeases: {},
     };
 }
-function parseReply(value) {
-    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
-        throw new SquareError('invalid_args', 'Invalid square: malformed act reply metadata.');
-    }
-    return value;
+function normalizedLines(value) {
+    const normalized = value.replace(/\r\n/g, '\n').trim();
+    return normalized === '' ? [] : normalized.split('\n');
 }
-function normalizeActMeta(marker, kind, actor, head) {
-    if (marker.kind === undefined || marker.actor === undefined) {
-        throw new SquareError('invalid_args', 'Invalid square: act marker is missing kind/actor metadata.');
-    }
-    if (marker.kind !== kind) {
-        throw new SquareError('invalid_args', `Invalid square: act marker kind ${marker.kind} does not match ${kind}.`);
+function readGuide(name) {
+    try {
+        return fs.readFileSync(new URL(`../guides/${name}.md`, import.meta.url), 'utf8').trim();
     }
-    if (!sameName(marker.actor, actor)) {
-        throw new SquareError('invalid_args', `Invalid square: act marker actor ${marker.actor} does not match ${actor}.`);
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new SquareError('invalid_args', `Unknown square guide: ${name}`);
+        }
+        throw error;
     }
-    if (marker.at === undefined) {
-        throw new SquareError('invalid_args', `Invalid square: act marker is missing timestamp for ${kind} ${actor}.`);
+}
+export function createSquareDoc(options, snippet) {
+    const guides = [readGuide('participant')];
+    if (options.template !== undefined)
+        guides.push(readGuide(options.template));
+    return {
+        hardCap: options.hardCap,
+        ...(options.throttlePerMinute === undefined ? {} : { throttlePerMinute: options.throttlePerMinute }),
+        preamble: normalizedLines(snippet),
+        warmup: normalizedLines(guides.join('\n\n')),
+        acts: [],
+        runtime: emptyRuntimeState(),
+    };
+}
+export function encodeSquare(doc) {
+    return encodeEnvelope(SQUARE_MAGIC, validateSquareDoc(doc));
+}
+export function decodeSquare(bytes) {
+    return validateSquareDoc(decodeEnvelope(bytes, SQUARE_MAGIC));
+}
+export function encodeArchive(acts) {
+    if (!validateActs(acts))
+        throw invalidArtifact('archive activity schema is malformed.');
+    return encodeEnvelope(ARCHIVE_MAGIC, { acts });
+}
+export function decodeArchive(bytes) {
+    const value = decodeEnvelope(bytes, ARCHIVE_MAGIC);
+    if (!isObject(value) || !hasExactKeys(value, ['acts']) || !validateActs(value.acts)) {
+        throw invalidArtifact('archive schema is malformed.');
     }
-    if (marker.at !== head.at) {
-        throw new SquareError('invalid_args', `Invalid square: act marker timestamp does not match ${kind} ${actor}.`);
+    return value.acts;
+}
+function readArtifact(squarePath) {
+    try {
+        return fs.readFileSync(squarePath);
     }
-    if (marker.reply !== undefined && kind !== 'say') {
-        throw new SquareError('invalid_args', 'Invalid square: only say acts may reply to another activity.');
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new SquareError('not_found', `square file not found: ${squarePath}`);
+        }
+        throw error;
     }
-    return { index: marker.index, ...(marker.reach !== undefined ? { reach: marker.reach } : {}), ...(marker.reply !== undefined ? { reply: marker.reply } : {}) };
-}
-export function activitiesSourceLines(text) {
-    const lines = text.split('\n');
-    const marker = findActivitiesMarker(lines);
-    if (marker < 0)
-        throw new SquareError('invalid_args', 'Invalid square: missing ACTIVITIES section.');
-    let start = marker + 1;
-    while (start < lines.length && (lines[start] === '' || isSquareMarker(lines[start])))
-        start++;
-    return lines.slice(start);
-}
-export function parseParticipantHeading(line) {
-    const match = line.match(/^### (.+)\s*$/);
-    return match ? match[1] : null;
-}
-export function parseActLine(line, actor) {
-    const match = line.match(/^_(say|join|done|hold|resume) · ([^_]+)_\s*$/);
-    if (!match)
-        return null;
-    const at = parseTimestamp(match[2]);
-    if (!Number.isFinite(at) || !V2_KINDS.has(match[1]))
-        return null;
-    return { kind: match[1], actor, at };
-}
-function isActSeparator(lines, index) {
-    return lines[index]?.trim().startsWith(ACT_MARKER_PREFIX) === true;
-}
-function parseActBlock(blockLines) {
-    let i = 0;
-    const marker = parseActMarker(blockLines[i]?.trim());
-    if (!marker)
-        throw new SquareError('invalid_args', `Invalid square: expected act marker, got: ${blockLines[i] ?? ''}`);
-    i++;
-    const actor = parseParticipantHeading(blockLines[i] ?? '');
-    if (!actor)
-        throw new SquareError('invalid_args', `Invalid square: expected participant heading, got: ${blockLines[i] ?? ''}`);
-    i++;
-    if (blockLines[i] === '')
-        i++;
-    const head = parseActLine(blockLines[i] ?? '', actor);
-    if (!head)
-        throw new SquareError('invalid_args', `Invalid square: expected act line, got: ${blockLines[i] ?? ''}`);
-    i++;
-    const meta = normalizeActMeta(marker, head.kind, actor, head);
-    let body = '';
-    if (head.kind === 'say' || head.kind === 'done' || head.kind === 'hold') {
-        if (blockLines[i] === '')
-            i++;
-        body = unquoteBody(blockLines.slice(i));
+}
+function requireSquareExtension(squarePath) {
+    if (!squarePath.endsWith('.square')) {
+        throw new SquareError('invalid_args', `Square artifacts must use the .square extension: ${squarePath}`);
     }
-    return { ...head, body, index: meta.index, ...(meta.reach !== undefined ? { reach: meta.reach } : {}), ...(meta.reply !== undefined ? { reply: meta.reply } : {}) };
-}
-function parseActs(text) {
-    const lines = activitiesSourceLines(text);
-    const acts = [];
-    const indexes = new Set();
-    let maxIndex = -1;
-    let detectedFirst = -1;
-    for (let i = 0; i < lines.length;) {
-        if (lines[i] === '') {
-            i++;
-            continue;
-        }
-        let end = i + 1;
-        while (end < lines.length && !isActSeparator(lines, end))
-            end++;
-        const act = parseActBlock(lines.slice(i, end));
-        if (detectedFirst === -1)
-            detectedFirst = act.index;
-        if (indexes.has(act.index))
-            throw new SquareError('invalid_args', `Invalid square: duplicate act index ${act.index}.`);
-        indexes.add(act.index);
-        maxIndex = Math.max(maxIndex, act.index);
-        acts.push(act);
-        i = end;
+}
+function atomicWrite(target, bytes) {
+    const temporary = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    try {
+        fs.writeFileSync(temporary, bytes);
+        fs.renameSync(temporary, target);
     }
-    if (indexes.size > 0) {
-        const first = detectedFirst;
-        if (Math.min(...indexes) !== first || indexes.size !== maxIndex - first + 1) {
-            throw new SquareError('invalid_args', 'Invalid square: act indexes must be contiguous from the first retained index.');
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
         }
+        catch { }
+        throw error;
     }
-    return { acts, nextActIndex: indexes.size > 0 ? maxIndex + 1 : 0 };
 }
-function isDivider(line) {
-    return line.trim() === '---';
+export function writeSquareFile(squarePath, doc) {
+    requireSquareExtension(squarePath);
+    atomicWrite(squarePath, encodeSquare(doc));
 }
-function trimSection(lines) {
-    while (lines.length > 0 && (lines[0] === '' || isDivider(lines[0])))
-        lines.shift();
-    while (lines.length > 0 && (lines[lines.length - 1] === '' || isDivider(lines[lines.length - 1])))
-        lines.pop();
+export function loadSquare(squarePath) {
+    requireSquareExtension(squarePath);
+    return decodeSquare(readArtifact(squarePath));
 }
-function unfixableResult(reason) {
-    return {
-        unfixable: reason,
-        problems: [],
-        hardCap: null,
-        preamble: [],
-        warmup: [],
-        acts: [],
-        quarantined: [],
-    };
+export function writeArchiveFile(archivePath, acts) {
+    atomicWrite(archivePath, encodeArchive(acts));
 }
-function tryParseV2ActBlock(blockLines) {
-    try {
-        const marker = parseActMarker(blockLines[0]?.trim());
-        if (!marker || marker.kind === undefined || marker.actor === undefined)
-            return { ok: false, reason: 'act marker is missing kind/actor metadata.' };
-        const actor = parseParticipantHeading(blockLines[1] ?? '');
-        if (!actor)
-            return { ok: false, reason: `act block missing participant heading, got: ${blockLines[1] ?? ''}` };
-        const headLine = blockLines[2] === '' ? blockLines[3] : blockLines[2];
-        if (!parseActLine(headLine ?? '', actor))
-            return { ok: false, reason: `act block missing or malformed timestamp line, got: ${headLine ?? ''}` };
-        return { ok: true, act: parseActBlock(blockLines) };
-    }
-    catch {
-        return { ok: false, reason: 'malformed act block.' };
-    }
+export function loadArchive(archivePath) {
+    return decodeArchive(readArtifact(archivePath));
 }
-function detectBlockParser(line) {
-    const trimmed = line.trim();
-    if (trimmed.startsWith(ACT_MARKER_PREFIX))
-        return tryParseV2ActBlock;
-    return null;
-}
-function isActBlockStart(line) {
-    return line.trim().startsWith('<!-- square:');
-}
-function diagnoseActs(text, problems) {
-    const lines = activitiesSourceLines(text);
-    const acts = [];
-    const quarantined = [];
-    const seenIndexes = new Set();
-    let i = 0;
-    while (i < lines.length) {
-        if (lines[i] === '') {
-            i++;
-            continue;
-        }
-        const parseBlock = detectBlockParser(lines[i]);
-        if (!parseBlock) {
-            problems.push({ kind: 'act_block', message: `expected act marker, got: ${lines[i]}` });
-            let j = i + 1;
-            while (j < lines.length && !isActBlockStart(lines[j]))
-                j++;
-            quarantined.push({ raw: lines.slice(i, j).join('\n'), reason: 'expected current-format act marker' });
-            i = j;
-            continue;
-        }
-        const blockStart = i;
-        let j = i + 1;
-        while (j < lines.length && !isActBlockStart(lines[j]))
-            j++;
-        const blockLines = lines.slice(blockStart, j);
-        const outcome = parseBlock(blockLines);
-        if (outcome.ok) {
-            const index = outcome.act.index;
-            if (seenIndexes.has(index))
-                problems.push({ kind: 'duplicate_index', message: `duplicate act index ${index}.` });
-            seenIndexes.add(index);
-            acts.push({ act: outcome.act, raw: blockLines.join('\n') });
-        }
-        else {
-            problems.push({ kind: 'act_block', message: outcome.reason });
-            quarantined.push({ raw: blockLines.join('\n'), reason: outcome.reason });
+export function probeSquare(squarePath) {
+    if (!squarePath.endsWith('.square'))
+        return undefined;
+    let descriptor;
+    try {
+        descriptor = fs.openSync(squarePath, 'r');
+        const magic = Buffer.alloc(SQUARE_MAGIC.length);
+        if (fs.readSync(descriptor, magic, 0, magic.length, 0) !== magic.length || !magic.equals(SQUARE_MAGIC)) {
+            return undefined;
         }
-        i = j;
     }
-    const uniqueIndexes = [...seenIndexes].sort((a, b) => a - b);
-    if (uniqueIndexes.length > 0) {
-        const min = uniqueIndexes[0];
-        const max = uniqueIndexes[uniqueIndexes.length - 1];
-        if (max - min + 1 !== uniqueIndexes.length) {
-            problems.push({ kind: 'non_contiguous_indexes', message: 'act indexes are not contiguous.' });
-        }
+    catch {
+        return undefined;
     }
-    return { acts, quarantined };
-}
-export function diagnoseSquare(text) {
-    const fmMatch = text.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
-    if (!fmMatch)
-        return unfixableResult('cannot locate frontmatter: missing opening/closing "---" delimiters.');
-    const frontmatter = fmMatch[1];
-    const lines = text.split('\n');
-    if (!lines.some((line) => line.trim() === WARMUP_MARKER) || !lines.some((line) => line.trim() === ACTIVITIES_MARKER)) {
-        return unfixableResult('cannot locate the warmup/activities section markers; the act stream boundaries are unknown.');
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
     }
-    const problems = [];
-    const fvMatch = frontmatter.match(/^format_version:\s*(\d+)\s*$/m);
-    const formatVersion = fvMatch ? parseInt(fvMatch[1], 10) : undefined;
-    if (formatVersion === undefined)
-        return unfixableResult('missing format_version in frontmatter. Create a new square with `square build`.');
-    if (formatVersion !== CURRENT_FORMAT_VERSION)
-        return unfixableResult(`format_version ${formatVersion} is no longer supported. Create a new square with \`square build\`.`);
-    let hardCap = null;
-    const hcMatch = frontmatter.match(/^hard_cap:\s*(-1|\d+)\s*$/m);
-    if (!hcMatch)
-        problems.push({ kind: 'hard_cap', message: 'missing or malformed hard_cap in frontmatter.' });
-    else
-        hardCap = hcMatch[1] === '-1' ? null : parseInt(hcMatch[1], 10);
-    let throttlePerMinute;
-    const tMatch = frontmatter.match(/^throttle_per_minute:\s*(\d+)\s*$/m);
-    if (tMatch)
-        throttlePerMinute = parseInt(tMatch[1], 10);
-    let preamble = [];
     try {
-        preamble = parsePreamble(text);
+        return loadSquare(squarePath);
     }
-    catch (err) {
-        problems.push({ kind: 'preamble', message: err instanceof Error ? err.message : String(err) });
+    catch {
+        return undefined;
     }
-    let warmup = [];
+}
+export function diagnoseSquareFile(squarePath) {
     try {
-        warmup = parseWarmup(text);
+        return { problems: [], doc: loadSquare(squarePath) };
     }
-    catch (err) {
-        problems.push({ kind: 'warmup', message: err instanceof Error ? err.message : String(err) });
+    catch (error) {
+        return {
+            unfixable: error instanceof Error ? error.message : String(error),
+            problems: [],
+        };
     }
-    const { acts, quarantined } = diagnoseActs(text, problems);
-    return {
-        formatVersion,
-        problems,
-        hardCap,
-        throttlePerMinute,
-        preamble,
-        warmup,
-        acts,
-        quarantined,
-    };
 }