@astrosheep/square 0.3.2

package/dist/artifact.js

@@ -0,0 +1,739 @@
+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 V1_EVENT_MARKER_PREFIX = '<!-- square:event';
+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 } : {}),
+    };
+    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');
+}
+export function emptyRuntimeState(nextActIndex = 0) {
+    return {
+        version: 2,
+        nextActIndex,
+        firstActIndex: 0,
+        cursors: {},
+        mentionReceipts: {},
+        leases: {},
+    };
+}
+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 loadRuntimeSidecar(squarePath) {
+    const sp = sidecarPath(squarePath);
+    try {
+        const raw = fs.readFileSync(sp, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!isObject(parsed) || typeof parsed.nextActIndex !== 'number' || !Number.isInteger(parsed.nextActIndex)) {
+            throw new Error('corrupt sidecar');
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return emptyRuntimeState(0);
+        }
+        throw err;
+    }
+}
+export function saveRuntimeSidecar(squarePath, runtime) {
+    fs.writeFileSync(sidecarPath(squarePath), JSON.stringify(runtime, null, 2));
+}
+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 parseStateBlock(frontmatter) {
+    const lines = frontmatter.split('\n');
+    const start = lines.findIndex((line) => /^mind_square_state:\s*\|\s*$/.test(line));
+    if (start < 0)
+        return undefined;
+    const body = [];
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.startsWith(' ') && !line.startsWith('\t') && /^[A-Za-z_][A-Za-z0-9_-]*:/.test(line))
+            break;
+        if (line.startsWith('  '))
+            body.push(line.slice(2));
+        else if (line.trim() === '')
+            body.push('');
+        else
+            break;
+    }
+    return body.join('\n').trim();
+}
+export function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(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) &&
+        (value.source === 'join' || value.source === 'watch' || value.source === 'api'));
+}
+export function isMentionReceipt(value) {
+    if (!isObject(value))
+        return false;
+    if (value.status !== 'delivered' && value.status !== 'presented')
+        return false;
+    if (typeof value.at !== 'number' || !Number.isFinite(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')
+        return false;
+    return true;
+}
+export function isMentionReceiptMap(value) {
+    return isObject(value) && Object.entries(value).every(([id, receipt]) => /^act_\d+$/.test(id) && isMentionReceipt(receipt));
+}
+export function isWatchLease(value) {
+    if (!isObject(value))
+        return false;
+    if (typeof value.leaseId !== 'string' || value.leaseId === '')
+        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.');
+    }
+    const version = parseInt(match[1], 10);
+    if (version !== CURRENT_FORMAT_VERSION) {
+        throw invalidVersionGuidance(`Invalid square: unsupported format_version ${version} (expected ${CURRENT_FORMAT_VERSION}).`);
+    }
+    return version;
+}
+export function parseSquare(text) {
+    parseFormatVersion(text);
+    const runtime = emptyRuntimeState(0);
+    const parsedActs = parseActs(text, 0);
+    runtime.nextActIndex = parsedActs.nextActIndex;
+    runtime.firstActIndex = parsedActs.firstActIndex;
+    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');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new SquareError('not_found', `square file not found: ${squarePath}`);
+        }
+        throw err;
+    }
+    const doc = parseSquare(text);
+    const sidecar = loadRuntimeSidecar(squarePath);
+    doc.runtime = sidecar;
+    if (sidecar.nextActIndex > doc.runtime.nextActIndex) {
+        doc.runtime.nextActIndex = sidecar.nextActIndex;
+    }
+    doc.runtime.firstActIndex = sidecar.firstActIndex;
+    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]);
+    }
+    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.');
+    }
+    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) } : {}),
+    };
+}
+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}.`);
+    }
+    if (!sameName(marker.actor, actor)) {
+        throw new SquareError('invalid_args', `Invalid square: act marker actor ${marker.actor} does not match ${actor}.`);
+    }
+    if (marker.at === undefined) {
+        throw new SquareError('invalid_args', `Invalid square: act marker is missing timestamp for ${kind} ${actor}.`);
+    }
+    if (marker.at !== head.at) {
+        throw new SquareError('invalid_args', `Invalid square: act marker timestamp does not match ${kind} ${actor}.`);
+    }
+    return { index: marker.index, ...(marker.reach !== undefined ? { reach: marker.reach } : {}) };
+}
+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 parseActs(text, _firstActIndex) {
+    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;
+        }
+        const marker = parseActMarker(lines[i]?.trim());
+        if (!marker)
+            throw new SquareError('invalid_args', `Invalid square: expected act marker, got: ${lines[i]}`);
+        i++;
+        const actor = parseParticipantHeading(lines[i]);
+        if (!actor)
+            throw new SquareError('invalid_args', `Invalid square: expected participant heading, got: ${lines[i]}`);
+        i++;
+        if (lines[i] === '')
+            i++;
+        const head = parseActLine(lines[i], actor);
+        if (!head)
+            throw new SquareError('invalid_args', `Invalid square: expected act line, got: ${lines[i] ?? ''}`);
+        i++;
+        const meta = normalizeActMeta(marker, head.kind, actor, head);
+        if (detectedFirst === -1)
+            detectedFirst = meta.index;
+        if (indexes.has(meta.index))
+            throw new SquareError('invalid_args', `Invalid square: duplicate act index ${meta.index}.`);
+        indexes.add(meta.index);
+        maxIndex = Math.max(maxIndex, meta.index);
+        let body = '';
+        if (head.kind === 'say' || head.kind === 'done' || head.kind === 'hold') {
+            if (lines[i] === '')
+                i++;
+            const bodyStart = i;
+            while (i < lines.length && !isActSeparator(lines, i))
+                i++;
+            body = unquoteBody(lines.slice(bodyStart, i));
+        }
+        acts.push({ ...head, body, index: meta.index, ...(meta.reach !== undefined ? { reach: meta.reach } : {}) });
+    }
+    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.');
+        }
+    }
+    return { acts, nextActIndex: indexes.size > 0 ? maxIndex + 1 : 0, firstActIndex: detectedFirst >= 0 ? detectedFirst : 0 };
+}
+function isDivider(line) {
+    return line.trim() === '---';
+}
+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();
+}
+function unfixableResult(reason) {
+    return {
+        unfixable: reason,
+        legacyParticipants: [],
+        problems: [],
+        hardCap: null,
+        preamble: [],
+        warmup: [],
+        acts: [],
+        quarantined: [],
+        runtimeRaw: undefined,
+    };
+}
+function parseLegacyEventMarker(line) {
+    if (line === undefined || !line.startsWith(V1_EVENT_MARKER_PREFIX))
+        return null;
+    const match = line.match(/^<!-- square:event\s+(\{.*\})\s*-->$/);
+    if (!match)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(match[1]);
+    }
+    catch {
+        return null;
+    }
+    if (!isObject(parsed) || typeof parsed.index !== 'number' || !Number.isInteger(parsed.index) || parsed.index < 0)
+        return null;
+    return {
+        index: parsed.index,
+        ...(typeof parsed.type === 'string' ? { type: parsed.type } : {}),
+        ...(typeof parsed.name === 'string' ? { name: parsed.name } : {}),
+        ...(typeof parsed.at === 'number' && Number.isFinite(parsed.at) ? { at: parsed.at } : {}),
+    };
+}
+function parseLegacyEventLine(line, actor) {
+    let match = line.match(/^_activity (\d+) · ([^_]+)_\s*$/);
+    if (match) {
+        const at = parseTimestamp(match[2]);
+        return Number.isFinite(at) ? { type: 'activity', actor, at, number: parseInt(match[1], 10) } : null;
+    }
+    match = line.match(/^_(joined|done|hold|resume) · ([^_]+)_\s*$/);
+    if (!match)
+        return null;
+    const at = parseTimestamp(match[2]);
+    if (!Number.isFinite(at))
+        return null;
+    const type = match[1] === 'joined' ? 'join' : match[1];
+    return { type, actor, at };
+}
+function normalizeLegacyActor(name) {
+    if (name === undefined || sameName(name, 'system'))
+        return 'unknown';
+    return name;
+}
+function mapLegacyEventToAct(marker, head, body) {
+    if (marker.type === undefined || marker.name === undefined)
+        return null;
+    if (marker.type !== head.type || !sameName(marker.name, head.actor))
+        return null;
+    switch (head.type) {
+        case 'activity':
+            return { kind: 'say', actor: head.actor, at: head.at, body, index: marker.index };
+        case 'join':
+            return { kind: 'join', actor: head.actor, at: head.at, body: '', index: marker.index };
+        case 'done':
+            return { kind: 'done', actor: head.actor, at: head.at, body, index: marker.index };
+        case 'hold':
+            return { kind: 'hold', actor: normalizeLegacyActor(head.actor), at: head.at, body, index: marker.index };
+        case 'resume':
+            return { kind: 'resume', actor: normalizeLegacyActor(head.actor), at: head.at, body: '', index: marker.index };
+        default:
+            return null;
+    }
+}
+function tryParseV2ActBlock(blockLines) {
+    try {
+        let i = 0;
+        const marker = parseActMarker(blockLines[i]?.trim());
+        if (!marker || marker.kind === undefined || marker.actor === undefined)
+            return { ok: false, reason: 'act marker is missing kind/actor metadata.' };
+        i++;
+        const actor = parseParticipantHeading(blockLines[i] ?? '');
+        if (!actor)
+            return { ok: false, reason: `act block missing participant heading, got: ${blockLines[i] ?? ''}` };
+        i++;
+        if (blockLines[i] === '')
+            i++;
+        const head = parseActLine(blockLines[i] ?? '', actor);
+        if (!head)
+            return { ok: false, reason: `act block missing or malformed timestamp line, got: ${blockLines[i] ?? ''}` };
+        i++;
+        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));
+        }
+        return { ok: true, act: { ...head, body, index: marker.index, ...(marker.reach !== undefined ? { reach: marker.reach } : {}) } };
+    }
+    catch {
+        return { ok: false, reason: 'malformed act block.' };
+    }
+}
+function tryParseV1EventBlock(blockLines) {
+    const marker = parseLegacyEventMarker(blockLines[0]?.trim());
+    if (!marker)
+        return { ok: false, reason: `expected event marker, got: ${blockLines[0] ?? ''}` };
+    let i = 1;
+    const actor = parseParticipantHeading(blockLines[i] ?? '');
+    if (!actor)
+        return { ok: false, reason: `event block missing participant heading, got: ${blockLines[i] ?? ''}` };
+    i++;
+    if (blockLines[i] === '')
+        i++;
+    const head = parseLegacyEventLine(blockLines[i] ?? '', actor);
+    if (!head)
+        return { ok: false, reason: `event block missing or malformed timestamp line, got: ${blockLines[i] ?? ''}` };
+    i++;
+    if (blockLines[i] === '')
+        i++;
+    const body = unquoteBody(blockLines.slice(i));
+    const act = mapLegacyEventToAct(marker, head, body);
+    return act ? { ok: true, act } : { ok: false, reason: 'legacy event metadata does not match its body.' };
+}
+function detectBlockParser(line) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith(ACT_MARKER_PREFIX))
+        return tryParseV2ActBlock;
+    if (trimmed.startsWith(V1_EVENT_MARKER_PREFIX))
+        return tryParseV1EventBlock;
+    return null;
+}
+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]}` });
+            quarantined.push({ raw: lines[i], reason: 'expected act marker' });
+            i++;
+            continue;
+        }
+        const blockStart = i;
+        let j = i + 1;
+        while (j < lines.length && detectBlockParser(lines[j]) === null)
+            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 });
+        }
+        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.' });
+        }
+    }
+    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.');
+    }
+    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\`.`);
+    const legacyParticipantsMatch = frontmatter.match(/^participants:[^\S\r\n]*(.*?)[^\S\r\n]*$/m);
+    const legacyParticipants = legacyParticipantsMatch
+        ? legacyParticipantsMatch[1].split(',').map((name) => name.trim()).filter(Boolean)
+        : [];
+    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 runtimeRaw;
+    // V3: runtime state is in the sidecar file, not in markdown.
+    const rawState = parseStateBlock(frontmatter);
+    if (rawState !== undefined && rawState !== '') {
+        try {
+            runtimeRaw = JSON.parse(rawState);
+        }
+        catch {
+            problems.push({ kind: 'runtime_state', message: 'malformed legacy mind_square_state JSON in frontmatter.' });
+        }
+    }
+    let preamble = [];
+    try {
+        preamble = parsePreamble(text);
+    }
+    catch (err) {
+        problems.push({ kind: 'preamble', message: err instanceof Error ? err.message : String(err) });
+    }
+    let warmup = [];
+    try {
+        warmup = parseWarmup(text);
+    }
+    catch (err) {
+        problems.push({ kind: 'warmup', message: err instanceof Error ? err.message : String(err) });
+    }
+    const { acts, quarantined } = diagnoseActs(text, problems);
+    return {
+        formatVersion,
+        legacyParticipants,
+        problems,
+        hardCap,
+        throttlePerMinute,
+        preamble,
+        warmup,
+        acts,
+        quarantined,
+        runtimeRaw,
+    };
+}