@agent-relay/factory 0.1.56 → 0.1.58

package/dist/feature-guardian/conversation.js

@@ -0,0 +1,1893 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { defineAgent } from '@agentworkforce/runtime';
+import { RelayFileApiError, RelayFileClient, RevisionConflictError, } from '@relayfile/sdk';
+import { githubClient, slackClient, } from '@relayfile/relay-helpers';
+export const GUARDIAN_CONVERSATION_STATE_PATH = '/memory/workspace/feature-guardian/conversations.json';
+export const GUARDIAN_CONFIRMATIONS_PATH = '/memory/workspace/feature-guardian/confirmations';
+export const GUARDIAN_REMEDIATIONS_PATH = '/memory/workspace/feature-guardian/remediations';
+export const GUARDIAN_STATE_TIMEOUT_MS = 5_000;
+export const GUARDIAN_WRITEBACK_TIMEOUT_MS = 15_000;
+export const GUARDIAN_WRITEBACK_POLL_MS = 250;
+const MAX_STATE_BYTES = 256 * 1024;
+const MAX_CONVERSATIONS = 512;
+const MAX_SEEN_EVENTS = 128;
+const MAX_EVIDENCE_ITEMS = 32;
+const MAX_TURNS = 12;
+const MAX_REMEDIATION_ATTEMPTS = 8;
+const UTF8_ENCODER = new TextEncoder();
+const PREVIEW_IMMUTABLE_CLAIMS = new WeakMap();
+export class GuardianStateConflictError extends Error {
+    constructor(message = 'feature guardian conversation state revision conflict') {
+        super(message);
+        this.name = 'GuardianStateConflictError';
+    }
+}
+/**
+ * Reusable feature-guardian factory. Repository adopters provide their catalog,
+ * procedures, gates, prompt, authority, and issue policy; this factory owns the
+ * scoped Slack listeners and dispatches every response through the shared state
+ * machine.
+ */
+export function defineFeatureGuardianAgent(options) {
+    const channelInput = options.channelInput ?? 'SLACK_CHANNEL';
+    const paths = [`/slack/channels/\${${channelInput}}/messages/**`];
+    return defineAgent({
+        triggers: {
+            slack: [
+                { on: 'message.created', paths, maxConcurrency: 1 },
+                { on: 'reaction.added', paths, maxConcurrency: 1 },
+            ],
+        },
+        schedules: options.schedules ?? [
+            { name: 'hourly-check', cron: '0 * * * *', tz: 'America/New_York' },
+        ],
+        handler: async (ctx, event) => {
+            if (event.type === 'cron.tick') {
+                await options.scheduled(ctx, event);
+                return;
+            }
+            await runGuardianConversationTurn(ctx, event, options.adapters);
+        },
+    });
+}
+/** A stable content revision suitable for binding a question to exact source text. */
+export function guardianContentRevision(content) {
+    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
+/** Stable identity for one question in one manifest generation. */
+export function guardianConversationId(question) {
+    return [
+        question.feature.id,
+        question.manifestRevision,
+        `g${question.generation}`,
+        question.channelId,
+        question.threadTs,
+    ].join(':');
+}
+/** Stable key shared by retries of one threaded response. */
+export function guardianReplyIdempotencyKey(record, eventId, purpose) {
+    return `feature-guardian:${record.id}:${eventId}:${purpose}`;
+}
+/** Immutable confirmation path. The filename is a hash so provider IDs never become paths. */
+export function guardianConfirmationPath(record) {
+    const identity = [
+        record.featureId,
+        record.manifestRevision,
+        `g${record.generation}`,
+        record.slack.channelId,
+        record.slack.threadTs,
+    ].join(':');
+    return `${GUARDIAN_CONFIRMATIONS_PATH}/${createHash('sha256').update(identity).digest('hex')}.json`;
+}
+/** Parse checkmark/wrench/question reactions and conversational text without an LLM guess. */
+export function classifyGuardianResponse(input) {
+    const reaction = (input.reaction ?? '').trim().toLowerCase().replaceAll('-', '_');
+    if (['white_check_mark', 'heavy_check_mark', 'ballot_box_with_check', 'check'].includes(reaction)) {
+        return 'affirmative';
+    }
+    if (['wrench', 'hammer_and_wrench', 'hammer', 'x'].includes(reaction))
+        return 'failure';
+    if (['question', 'grey_question', 'interrobang'].includes(reaction))
+        return 'untested';
+    const text = (input.text ?? '').trim().toLowerCase();
+    if (!text)
+        return 'ambiguous';
+    if (/\b(defer(?:red)?|manual|skip(?:ped)?|cannot run|can't run|blocked by credentials)\b/u.test(text)) {
+        return 'deferred';
+    }
+    if (/\b(untested|not tested|haven't tested|have not tested|unknown|unsure|don't know|do not know)\b/u.test(text)) {
+        return 'untested';
+    }
+    if (/\b(?:does(?:n't| not)|is(?:n't| not)|not)\s+(?:work(?:ing)?|pass(?:ing)?)\b/u.test(text)) {
+        return 'failure';
+    }
+    if (/^(?:not broken|not failing|no problems?|no issues?|works? for me)[.!\s]*$/u.test(text)) {
+        return 'affirmative';
+    }
+    if (/\b(broken|breaks?|failing|fails?|failed|regression|drift(?:ed)?|wrong|bug|problem|off)\b/u.test(text)) {
+        return 'failure';
+    }
+    if (/^(?:yes|yep|yeah|confirmed|works?|working|passes?|passed|all good|looks good|✅)[.!\s]*$/u.test(text)) {
+        return 'affirmative';
+    }
+    if (/\b(tested|verified|confirmed)\b/u.test(text) && /\b(works?|working|passes?|passed|expected|good)\b/u.test(text)) {
+        return 'affirmative';
+    }
+    return 'ambiguous';
+}
+/** Expand and fail-closed parse one Slack reply/reaction event. */
+export async function parseGuardianSlackEvent(event) {
+    if (!event.type.startsWith('slack.'))
+        return null;
+    const envelopeId = nonEmptyString(event.id);
+    if (!envelopeId || typeof event.expand !== 'function')
+        return null;
+    const expanded = await event.expand('full');
+    const root = asRecord(expanded?.data);
+    const payload = findSlackPayload(root);
+    if (!payload)
+        return null;
+    const item = asRecord(payload.item);
+    const isReaction = event.type.includes('reaction') || nonEmptyString(payload.reaction) !== undefined;
+    const channelId = nonEmptyString(payload.channel) ??
+        nonEmptyString(payload.channel_id) ??
+        nonEmptyString(item?.channel) ??
+        channelFromPath(event.resource?.path);
+    const messageTs = nonEmptyString(payload.ts) ??
+        nonEmptyString(payload.message_ts) ??
+        nonEmptyString(item?.ts) ??
+        messageTsFromPath(event.resource?.path);
+    const threadTs = isReaction
+        ? messageTs
+        : nonEmptyString(payload.thread_ts) ?? nonEmptyString(payload.threadTs) ?? '';
+    const actorId = nonEmptyString(payload.user) ??
+        nonEmptyString(payload.user_id) ??
+        nonEmptyString(event.summary?.actor?.id);
+    if (!channelId || !messageTs || !threadTs || !actorId)
+        return null;
+    if (!isReaction && messageTs === threadTs)
+        return null;
+    const providerEventTs = nonEmptyString(payload.event_ts) ?? (isReaction ? undefined : messageTs);
+    const occurredAt = canonicalTimestamp(event.occurredAt) ??
+        timestampFromSlackTs(providerEventTs ?? messageTs);
+    if (!occurredAt)
+        return null;
+    const resourceChannelId = channelFromPath(event.resource?.path);
+    const resourceMessageTs = messageTsFromPath(event.resource?.path);
+    if (resourceChannelId && resourceChannelId !== channelId)
+        return null;
+    if (resourceMessageTs &&
+        resourceMessageTs !== messageTs &&
+        (!isReaction && resourceMessageTs !== threadTs))
+        return null;
+    const providerIdentity = isReaction
+        ? providerEventTs ?? envelopeId
+        : messageTs;
+    const eventId = `slack:${createHash('sha256')
+        .update([
+        channelId,
+        threadTs,
+        messageTs,
+        actorId,
+        nonEmptyString(payload.reaction) ?? '',
+        providerIdentity,
+    ].join(':'))
+        .digest('hex')}`;
+    const eventOrder = [occurredAt, slackTsOrder(providerEventTs ?? messageTs), messageTs, eventId].join(':');
+    return {
+        eventId,
+        eventOrder,
+        occurredAt,
+        channelId,
+        threadTs,
+        messageTs,
+        actorId,
+        text: nonEmptyString(payload.text) ?? '',
+        ...(nonEmptyString(payload.reaction) ? { reaction: nonEmptyString(payload.reaction) } : {}),
+        isReaction,
+        isBot: payload.user_is_bot === true ||
+            Boolean(nonEmptyString(payload.bot_id)) ||
+            nonEmptyString(payload.subtype) === 'bot_message',
+    };
+}
+/** Register a provider-confirmed question before the scheduled cycle advances. */
+export async function registerGuardianQuestion(ctx, question, dependencies = {}) {
+    const store = dependencies.conversationStore ?? createConversationStore(ctx);
+    const now = (dependencies.now ?? (() => new Date()))().toISOString();
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const snapshot = await store.load();
+        const state = snapshot?.state ?? emptyConversationState();
+        const id = guardianConversationId(question);
+        const existing = state.records.find((record) => record.id === id);
+        if (existing) {
+            if (!sameQuestion(existing, question)) {
+                throw new Error('guardian question identity collided with different question data');
+            }
+            return existing;
+        }
+        const record = {
+            ...question,
+            id,
+            status: 'asked',
+            turnCount: 0,
+            clarificationCount: 0,
+            seenEventIds: [],
+            evidence: [],
+            updatedAt: now,
+        };
+        const retained = retainConversationCapacity(state.records, record);
+        try {
+            await store.save({ ...state, records: [...retained, record] }, snapshot);
+            return record;
+        }
+        catch (error) {
+            if (!(error instanceof GuardianStateConflictError) || attempt === 2)
+                throw error;
+        }
+    }
+    throw new Error('unreachable guardian question registration retry');
+}
+/** Own one correlated Slack response through a durable or explicitly deferred outcome. */
+export async function runGuardianConversationTurn(ctx, event, adapters, dependencies = {}) {
+    const parsed = await parseGuardianSlackEvent(event);
+    if (!parsed || parsed.isBot)
+        return;
+    const configuredChannel = resolvedInput(ctx, 'SLACK_CHANNEL');
+    if (!configuredChannel || parsed.channelId !== configuredChannel) {
+        ctx.log('warn', 'feature-guardian.event-rejected', {
+            reason: 'unauthorized-channel',
+            channel: parsed.channelId,
+        });
+        return;
+    }
+    if (parsed.actorId === resolvedInput(ctx, 'SLACK_BOT_USER')) {
+        ctx.log('info', 'feature-guardian.event-ignored', { reason: 'configured-bot-actor' });
+        return;
+    }
+    const store = dependencies.conversationStore ?? createConversationStore(ctx);
+    const confirmationStore = dependencies.confirmationStore ?? createConfirmationStore(ctx);
+    const issueWriter = dependencies.issueWriter ?? createGithubIssueWriter(ctx);
+    const createSlackClient = dependencies.createSlackClient ?? slackClient;
+    const now = dependencies.now ?? (() => new Date());
+    let snapshot = await store.load();
+    if (!snapshot)
+        return;
+    const correlated = findCorrelatedConversation(snapshot.state, parsed);
+    if (!correlated) {
+        ctx.log('info', 'feature-guardian.event-ignored', {
+            reason: 'unrelated-thread',
+            channel: parsed.channelId,
+            threadTs: parsed.threadTs,
+            messageTs: parsed.messageTs,
+        });
+        return;
+    }
+    let record = correlated;
+    if (isTerminal(record.status))
+        return;
+    if (Date.parse(parsed.occurredAt) < Date.parse(record.askedAt)) {
+        ctx.log('info', 'feature-guardian.event-ignored', {
+            reason: 'event-predates-question',
+            eventId: parsed.eventId,
+            conversationId: record.id,
+        });
+        return;
+    }
+    // A durable pending turn always owns the conversation. Resume it before
+    // considering a later delivery so a restart or out-of-order event cannot
+    // overwrite procedure evidence, a confirmation write, or an issue receipt.
+    const pendingBeforeResume = record.pending;
+    if (pendingBeforeResume) {
+        await resumePendingTurn();
+        if (isTerminal(record.status) || record.pending)
+            return;
+        if (pendingBeforeResume.eventId === parsed.eventId || record.seenEventIds.includes(parsed.eventId)) {
+            return;
+        }
+        if (parsed.eventOrder <= pendingBeforeResume.eventOrder) {
+            ctx.log('info', 'feature-guardian.event-ignored', {
+                reason: 'superseded-out-of-order-event',
+                eventId: parsed.eventId,
+                conversationId: record.id,
+            });
+            return;
+        }
+    }
+    if (record.seenEventIds.includes(parsed.eventId))
+        return;
+    if (record.lastProcessedEventOrder &&
+        parsed.eventOrder <= record.lastProcessedEventOrder) {
+        ctx.log('info', 'feature-guardian.event-ignored', {
+            reason: 'delayed-event-precedes-conversation-watermark',
+            eventId: parsed.eventId,
+            conversationId: record.id,
+        });
+        return;
+    }
+    const catalog = await adapters.loadCatalog(ctx);
+    if (catalog.manifestRevision !== record.manifestRevision ||
+        catalog.procedureRevision !== record.procedureRevision) {
+        const turn = pendingTurn(parsed, 'deferred', {
+            source: 'system',
+            result: 'manual',
+            summary: 'The manifest or procedure changed after this question was posted; refusing to confirm a different revision.',
+        });
+        snapshot = await checkpointPending(snapshot, record, turn, 'deferred-recorded');
+        record = requireRecordById(snapshot.state, record.id);
+        await finishDeferred(record, turn.evidence?.summary ?? 'Revision changed before verification.');
+        return;
+    }
+    const response = classifyGuardianResponse({ text: parsed.text, reaction: parsed.reaction });
+    const actorEvidence = {
+        source: 'actor',
+        result: response === 'affirmative'
+            ? 'positive'
+            : response === 'failure'
+                ? 'negative'
+                : response === 'deferred'
+                    ? 'manual'
+                    : 'unknown',
+        summary: parsed.reaction
+            ? `Slack reaction :${parsed.reaction}: from ${parsed.actorId}`
+            : `Slack reply from ${parsed.actorId}: ${bounded(parsed.text, 1_000)}`,
+    };
+    const turn = pendingTurn(parsed, response, actorEvidence);
+    if (response === 'ambiguous') {
+        await clarify(turn);
+        return;
+    }
+    if ((response === 'failure' || response === 'untested') && record.turnCount === 0) {
+        await clarify(turn);
+        return;
+    }
+    if (response === 'affirmative' && adapters.isAuthorizedConfirmer(ctx, parsed.actorId)) {
+        if (!hasActorConfirmationEvidence(parsed.text)) {
+            await clarify(turn);
+            return;
+        }
+        snapshot = await checkpointPending(snapshot, record, turn, 'confirmation-recorded', true, { kind: 'actor', verifier: parsed.actorId });
+        record = requireRecordById(snapshot.state, record.id);
+        await finishConfirmation(record, turn);
+        return;
+    }
+    if (response === 'deferred') {
+        snapshot = await checkpointPending(snapshot, record, turn, 'deferred-recorded', true);
+        record = requireRecordById(snapshot.state, record.id);
+        await finishDeferred(record, actorEvidence.summary);
+        return;
+    }
+    const procedure = await adapters.resolveProcedure(ctx, record.feature);
+    const gate = await adapters.gateTier(ctx, record.feature, procedure);
+    if (gate.outcome !== 'available') {
+        const gateEvidence = {
+            source: 'system',
+            result: gate.outcome,
+            summary: gate.reason,
+        };
+        const deferredTurn = { ...turn, response: 'deferred', evidence: gateEvidence };
+        snapshot = await checkpointPending(snapshot, record, deferredTurn, 'deferred-recorded', true);
+        record = requireRecordById(snapshot.state, record.id);
+        await finishDeferred(record, gate.reason);
+        return;
+    }
+    snapshot = await checkpointPending(snapshot, record, turn, 'verifying', true);
+    record = requireRecordById(snapshot.state, record.id);
+    await resumePendingTurn(procedure, true);
+    async function resumePendingTurn(preResolvedProcedure, prerequisitesValidated = false) {
+        if (!snapshot || !record.pending)
+            return;
+        const pending = record.pending;
+        if (record.status === 'confirmation-recorded') {
+            await finishConfirmation(record, pending);
+            return;
+        }
+        if (record.status === 'remediation-recorded') {
+            if (!record.issue)
+                throw new Error('remediation-recorded state is missing its issue receipt');
+            await finishRemediation(record, record.issue);
+            return;
+        }
+        if (record.status === 'deferred-recorded') {
+            await finishDeferred(record, pending.evidence?.summary ?? 'Verification deferred.');
+            return;
+        }
+        if (record.status !== 'verifying')
+            return;
+        if (!prerequisitesValidated) {
+            const currentCatalog = await adapters.loadCatalog(ctx);
+            if (currentCatalog.manifestRevision !== record.manifestRevision ||
+                currentCatalog.procedureRevision !== record.procedureRevision) {
+                await deferPendingVerification('The manifest or procedure changed while verification was pending; refusing to run or confirm a different revision.', 'manual');
+                return;
+            }
+        }
+        const procedure = preResolvedProcedure ?? await adapters.resolveProcedure(ctx, record.feature);
+        if (!pending.verification && !prerequisitesValidated) {
+            const gate = await adapters.gateTier(ctx, record.feature, procedure);
+            if (gate.outcome !== 'available') {
+                await deferPendingVerification(gate.reason, gate.outcome);
+                return;
+            }
+        }
+        const result = pending.verification ?? await adapters.runProcedure(ctx, record.feature, procedure, guardianReplyIdempotencyKey(record, pending.eventId, 'procedure'));
+        if (!pending.verification) {
+            const next = replaceRecord(snapshot.state, record.id, {
+                ...record,
+                pending: { ...pending, verification: result },
+                evidence: appendEvidence(record.evidence, result),
+                updatedAt: now().toISOString(),
+            });
+            snapshot = await store.save(next, snapshot);
+            record = requireRecordById(snapshot.state, record.id);
+        }
+        const evidence = record.evidence;
+        if (result.outcome === 'passed') {
+            if (pending.response === 'failure') {
+                const reportedDefect = adapters.classifyDefect(record.feature, pending, evidence);
+                if (record.clarificationCount >= 1 &&
+                    ['test', 'manifest', 'procedure', 'documentation'].includes(reportedDefect) &&
+                    adapters.isDefectEstablished(record.feature, pending, evidence)) {
+                    await recordRemediation(result, reportedDefect);
+                    return;
+                }
+                const clarificationNumber = record.clarificationCount + 1;
+                const text = adapters.clarification(record.feature, procedure, { ...pending, evidence: result, verification: result }, clarificationNumber);
+                const receipt = await postThreadReply(createSlackClient, record, text, guardianReplyIdempotencyKey(record, pending.eventId, 'post-check-clarification'));
+                const next = replaceRecord(snapshot.state, record.id, {
+                    ...record,
+                    status: 'discussing',
+                    clarificationCount: clarificationNumber,
+                    seenEventIds: appendSeen(record.seenEventIds, pending.eventId),
+                    lastProcessedEventOrder: pending.eventOrder,
+                    pending: undefined,
+                    finalReplyTs: receipt,
+                    updatedAt: now().toISOString(),
+                });
+                snapshot = await store.save(next, snapshot);
+                record = requireRecordById(snapshot.state, record.id);
+                return;
+            }
+            const next = replaceRecord(snapshot.state, record.id, {
+                ...record,
+                status: 'confirmation-recorded',
+                confirmationBasis: { kind: 'procedure', verifier: result.verifier },
+                updatedAt: now().toISOString(),
+            });
+            snapshot = await store.save(next, snapshot);
+            record = requireRecordById(snapshot.state, record.id);
+            await finishConfirmation(record, pending);
+            return;
+        }
+        if (result.outcome === 'skip' || result.outcome === 'manual') {
+            const next = replaceRecord(snapshot.state, record.id, {
+                ...record,
+                status: 'deferred-recorded',
+                pending: { ...pending, response: 'deferred', evidence: result },
+                updatedAt: now().toISOString(),
+            });
+            snapshot = await store.save(next, snapshot);
+            record = requireRecordById(snapshot.state, record.id);
+            await finishDeferred(record, result.summary);
+            return;
+        }
+        const defectKind = adapters.classifyDefect(record.feature, pending, evidence);
+        await recordRemediation(result, defectKind);
+    }
+    async function deferPendingVerification(reason, outcome) {
+        if (!snapshot || !record.pending)
+            return;
+        const deferredPending = {
+            ...record.pending,
+            response: 'deferred',
+            evidence: { source: 'system', result: outcome, summary: reason },
+        };
+        const next = replaceRecord(snapshot.state, record.id, {
+            ...record,
+            status: 'deferred-recorded',
+            pending: deferredPending,
+            evidence: appendEvidence(record.evidence, deferredPending.evidence),
+            updatedAt: now().toISOString(),
+        });
+        snapshot = await store.save(next, snapshot);
+        record = requireRecordById(snapshot.state, record.id);
+        await finishDeferred(record, reason);
+    }
+    async function recordRemediation(result, defectKind) {
+        if (!snapshot || !record.pending)
+            return;
+        const pending = record.pending;
+        const evidence = record.evidence;
+        const policy = adapters.issuePolicy({
+            feature: record.feature,
+            conversation: { ...record, evidence },
+            defectKind,
+            slackBacklink: slackThreadBacklink(record.channelId, record.threadTs),
+        });
+        const routedRepository = adapters.repositoryForFeature(record.feature);
+        if (policy.repository !== routedRepository) {
+            throw new Error(`guardian issue policy routed ${policy.repository}, expected ${routedRepository}`);
+        }
+        const receipt = await issueWriter.upsert(policy);
+        if (receipt.repository !== routedRepository || receipt.dedupeKey !== policy.dedupeKey) {
+            throw new Error('guardian issue receipt did not match the authorized repository/dedupe key');
+        }
+        const next = replaceRecord(snapshot.state, record.id, {
+            ...record,
+            status: 'remediation-recorded',
+            issue: receipt,
+            pending: { ...pending, defectKind, evidence: result },
+            updatedAt: now().toISOString(),
+        });
+        snapshot = await store.save(next, snapshot);
+        record = requireRecordById(snapshot.state, record.id);
+        await finishRemediation(record, receipt);
+    }
+    async function clarify(turn) {
+        if (!snapshot)
+            return;
+        if (record.turnCount >= MAX_TURNS) {
+            snapshot = await checkpointPending(snapshot, record, {
+                ...turn,
+                response: 'deferred',
+                evidence: {
+                    source: 'system',
+                    result: 'manual',
+                    summary: `Clarification stopped after the bounded ${MAX_TURNS}-turn limit.`,
+                },
+            }, 'deferred-recorded', true);
+            record = requireRecordById(snapshot.state, record.id);
+            await finishDeferred(record, `Clarification stopped after ${MAX_TURNS} turns.`);
+            return;
+        }
+        const procedure = await adapters.resolveProcedure(ctx, record.feature);
+        const clarificationNumber = record.clarificationCount + 1;
+        const text = adapters.clarification(record.feature, procedure, turn, clarificationNumber);
+        const receipt = await postThreadReply(createSlackClient, record, text, guardianReplyIdempotencyKey(record, turn.eventId, 'clarification'));
+        const nextRecord = {
+            ...record,
+            status: 'discussing',
+            turnCount: record.turnCount + 1,
+            clarificationCount: clarificationNumber,
+            seenEventIds: appendSeen(record.seenEventIds, turn.eventId),
+            lastProcessedEventOrder: turn.eventOrder,
+            evidence: appendEvidence(record.evidence, turn.evidence),
+            finalReplyTs: receipt,
+            updatedAt: now().toISOString(),
+        };
+        snapshot = await store.save(replaceRecord(snapshot.state, record.id, nextRecord), snapshot);
+        record = requireRecordById(snapshot.state, record.id);
+    }
+    async function finishConfirmation(current, turn) {
+        if (!snapshot)
+            return;
+        // Bind the immutable timestamp to the provider event, not the retry wall
+        // clock, so a post-before-checkpoint retry produces byte-identical evidence.
+        const confirmation = confirmationRecord(current, turn, turn.eventOccurredAt);
+        const confirmationPath = await confirmationStore.append(confirmation);
+        if (current.confirmationPath !== confirmationPath) {
+            const next = replaceRecord(snapshot.state, current.id, {
+                ...current,
+                confirmationPath,
+                updatedAt: now().toISOString(),
+            });
+            snapshot = await store.save(next, snapshot);
+            current = requireRecordById(snapshot.state, current.id);
+            record = current;
+        }
+        const procedureEvidence = [...current.evidence]
+            .reverse()
+            .find((entry) => entry.source === 'procedure');
+        const summary = procedureEvidence
+            ? `✅ Confirmed *${current.feature.name}* for manifest \`${shortRevision(current.manifestRevision)}\`. ${formatEvidenceForSlack(procedureEvidence)}`
+            : `✅ Confirmed *${current.feature.name}* for manifest \`${shortRevision(current.manifestRevision)}\` from ${turn.actorId}'s response.`;
+        const replyTs = await postThreadReply(createSlackClient, current, summary, guardianReplyIdempotencyKey(current, turn.eventId, 'confirmed'));
+        const terminal = {
+            ...current,
+            status: 'confirmed',
+            pending: undefined,
+            seenEventIds: appendSeen(current.seenEventIds, turn.eventId),
+            lastProcessedEventOrder: turn.eventOrder,
+            finalReplyTs: replyTs,
+            updatedAt: now().toISOString(),
+        };
+        snapshot = await store.save(replaceRecord(snapshot.state, current.id, terminal), snapshot);
+        record = requireRecordById(snapshot.state, current.id);
+    }
+    async function finishRemediation(current, issue) {
+        if (!snapshot || !current.pending)
+            return;
+        const replyTs = await postThreadReply(createSlackClient, current, `🔧 Verification established a ${current.pending.defectKind ?? 'feature'} defect for *${current.feature.name}*. Remediation: ${issue.url}`, guardianReplyIdempotencyKey(current, current.pending.eventId, 'remediation'));
+        const terminal = {
+            ...current,
+            status: 'remediation-open',
+            pending: undefined,
+            seenEventIds: appendSeen(current.seenEventIds, current.pending.eventId),
+            lastProcessedEventOrder: current.pending.eventOrder,
+            finalReplyTs: replyTs,
+            updatedAt: now().toISOString(),
+        };
+        snapshot = await store.save(replaceRecord(snapshot.state, current.id, terminal), snapshot);
+        record = requireRecordById(snapshot.state, current.id);
+    }
+    async function finishDeferred(current, reason) {
+        if (!snapshot || !current.pending)
+            return;
+        const evidenceResult = current.pending.verification?.result ?? current.pending.evidence?.result;
+        const outcome = evidenceResult === 'skip' ? 'SKIP' : 'MANUAL';
+        const replyTs = await postThreadReply(createSlackClient, current, `🟡 *${current.feature.name}* remains unconfirmed: ${reason} Result: ${outcome}.`, guardianReplyIdempotencyKey(current, current.pending.eventId, 'deferred'));
+        const terminal = {
+            ...current,
+            status: 'deferred',
+            pending: undefined,
+            seenEventIds: appendSeen(current.seenEventIds, current.pending.eventId),
+            lastProcessedEventOrder: current.pending.eventOrder,
+            finalReplyTs: replyTs,
+            updatedAt: now().toISOString(),
+        };
+        snapshot = await store.save(replaceRecord(snapshot.state, current.id, terminal), snapshot);
+        record = requireRecordById(snapshot.state, current.id);
+    }
+    async function checkpointPending(currentSnapshot, current, turn, status, countTurn = false, confirmationBasis) {
+        const nextRecord = {
+            ...current,
+            status,
+            turnCount: current.turnCount + (countTurn ? 1 : 0),
+            pending: turn,
+            ...(confirmationBasis ? { confirmationBasis } : {}),
+            lastProcessedEventOrder: turn.eventOrder,
+            evidence: appendEvidence(current.evidence, turn.evidence),
+            updatedAt: now().toISOString(),
+        };
+        return store.save(replaceRecord(currentSnapshot.state, current.id, nextRecord), currentSnapshot);
+    }
+}
+/** Exact-revision store used by the reusable state machine. */
+export function createSdkConversationStore(credentials, options = {}) {
+    const client = relayfileClient(credentials, options.fetchImpl);
+    const timeoutMs = options.timeoutMs ?? GUARDIAN_STATE_TIMEOUT_MS;
+    return exactStore({
+        client,
+        credentials,
+        path: GUARDIAN_CONVERSATION_STATE_PATH,
+        timeoutMs,
+        parse: parseConversationState,
+    });
+}
+/** Exact create-only immutable confirmation store. */
+export function createSdkConfirmationStore(credentials, options = {}) {
+    const client = relayfileClient(credentials, options.fetchImpl);
+    const timeoutMs = options.timeoutMs ?? GUARDIAN_STATE_TIMEOUT_MS;
+    return {
+        append: async (record) => {
+            const canonical = parseConfirmationRecord(record);
+            const path = guardianConfirmationPath(canonical);
+            const content = `${JSON.stringify(canonical)}\n`;
+            assertBoundedContent(content, 'guardian confirmation');
+            return withDeadline('guardian confirmation append', timeoutMs, async (signal) => {
+                const existing = await readExactFile(client, credentials.workspaceId, path, signal);
+                if (existing) {
+                    if (existing.content !== content)
+                        throw new Error('immutable guardian confirmation already differs');
+                    return path;
+                }
+                await writeExactFile(client, credentials.workspaceId, path, '0', content, signal);
+                const readBack = await readExactFile(client, credentials.workspaceId, path, signal);
+                if (!readBack || readBack.content !== content) {
+                    throw new Error('guardian confirmation read-back did not match');
+                }
+                return path;
+            });
+        },
+    };
+}
+function createConversationStore(ctx) {
+    const credentials = ctx.credentials.tryRequire();
+    if (credentials)
+        return createSdkConversationStore(credentials.relayfile);
+    if (ctx.agent.id === 'sim-agent' && ctx.deployment.id === 'sim-deployment') {
+        return previewConversationStore(ctx);
+    }
+    throw new Error('exact Relayfile credentials are required for guardian conversations');
+}
+function createConfirmationStore(ctx) {
+    const credentials = ctx.credentials.tryRequire();
+    if (credentials)
+        return createSdkConfirmationStore(credentials.relayfile);
+    if (ctx.agent.id === 'sim-agent' && ctx.deployment.id === 'sim-deployment') {
+        return {
+            append: async (record) => {
+                const canonical = parseConfirmationRecord(record);
+                const path = guardianConfirmationPath(canonical);
+                const content = `${JSON.stringify(canonical)}\n`;
+                let existing;
+                try {
+                    existing = await ctx.files.read(path);
+                }
+                catch (error) {
+                    if (!String(error).includes('ENOENT'))
+                        throw error;
+                }
+                if (existing !== undefined && existing !== content) {
+                    throw new Error('immutable guardian confirmation already differs');
+                }
+                if (existing === undefined)
+                    await ctx.files.write(path, content);
+                return path;
+            },
+        };
+    }
+    throw new Error('exact Relayfile credentials are required for guardian confirmations');
+}
+function previewConversationStore(ctx) {
+    const load = async () => {
+        let content;
+        try {
+            content = await ctx.files.read(GUARDIAN_CONVERSATION_STATE_PATH);
+        }
+        catch (error) {
+            if (String(error).includes('ENOENT'))
+                return null;
+            throw error;
+        }
+        assertBoundedContent(content, 'guardian conversation state');
+        const state = parseConversationState(JSON.parse(content));
+        return { state, revision: previewRevision(state) };
+    };
+    return {
+        load,
+        save: async (state, expected) => {
+            const canonical = parseConversationState(state);
+            const current = await load();
+            if (current?.revision !== expected?.revision)
+                throw new GuardianStateConflictError();
+            assertConversationTransition(expected?.state ?? null, canonical);
+            const content = `${JSON.stringify(canonical)}\n`;
+            assertBoundedContent(content, 'guardian conversation state');
+            await ctx.files.write(GUARDIAN_CONVERSATION_STATE_PATH, content);
+            const readBack = await load();
+            if (!readBack || JSON.stringify(readBack.state) !== JSON.stringify(canonical)) {
+                throw new Error('guardian conversation read-back did not match');
+            }
+            return readBack;
+        },
+    };
+}
+function exactStore(input) {
+    const load = () => withDeadline('guardian conversation load', input.timeoutMs, async (signal) => {
+        const file = await readExactFile(input.client, input.credentials.workspaceId, input.path, signal);
+        if (!file)
+            return null;
+        assertBoundedContent(file.content, 'guardian conversation state');
+        return {
+            state: input.parse(JSON.parse(file.content)),
+            revision: file.revision,
+        };
+    });
+    return {
+        load,
+        save: (state, expected) => {
+            const canonical = input.parse(state);
+            assertConversationTransition(expected?.state ?? null, canonical);
+            const content = `${JSON.stringify(canonical)}\n`;
+            assertBoundedContent(content, 'guardian conversation state');
+            return withDeadline('guardian conversation save', input.timeoutMs, async (signal) => {
+                try {
+                    await writeExactFile(input.client, input.credentials.workspaceId, input.path, expected?.revision ?? '0', content, signal);
+                }
+                catch (error) {
+                    if (error instanceof RevisionConflictError ||
+                        (error instanceof RelayFileApiError && error.status === 409)) {
+                        throw new GuardianStateConflictError();
+                    }
+                    throw error;
+                }
+                const readBack = await readExactFile(input.client, input.credentials.workspaceId, input.path, signal);
+                if (!readBack || readBack.content !== content) {
+                    throw new Error('guardian conversation read-back did not match');
+                }
+                return { state: canonical, revision: readBack.revision };
+            });
+        },
+    };
+}
+export function createGithubIssueWriter(ctx, client = githubClient({
+    writebackTimeoutMs: GUARDIAN_WRITEBACK_TIMEOUT_MS,
+    writebackPollMs: GUARDIAN_WRITEBACK_POLL_MS,
+})) {
+    return {
+        upsert: async (policy) => {
+            const [owner, repo, extra] = policy.repository.split('/');
+            if (!owner || !repo || extra)
+                throw new Error('guardian issue repository must be owner/repo');
+            const receiptPath = remediationReceiptPath(policy.dedupeKey);
+            const savedReceipt = await readImmutableJson(ctx, receiptPath);
+            const bodyRevision = guardianContentRevision(policy.body);
+            if (savedReceipt) {
+                const receipt = parseDurableIssueReceipt(savedReceipt, policy);
+                if (providerText(asRecord(savedReceipt)?.bodyRevision) !== bodyRevision) {
+                    await updateExistingIssueEvidence(ctx, client, owner, repo, receipt.number, policy);
+                }
+                return receipt;
+            }
+            const issues = await listGithubIssues(ctx, client, owner, repo);
+            const match = issues
+                .map(unwrapProviderRecord)
+                .find((issue) => providerText(issue.body).includes(remediationMarker(policy.dedupeKey)));
+            if (match) {
+                const number = providerNumber(match.number) ?? providerNumber(match.id);
+                const url = providerText(match.html_url) || providerText(match.url);
+                if (!number || !url)
+                    throw new Error('deduplicated guardian issue is missing number/url');
+                if (providerText(match.body) !== policy.body) {
+                    await updateExistingIssueEvidence(ctx, client, owner, repo, number, policy);
+                }
+                const receipt = { repository: policy.repository, number, url, dedupeKey: policy.dedupeKey };
+                await appendImmutableJson(ctx, receiptPath, { ...receipt, bodyRevision });
+                return receipt;
+            }
+            for (let attempt = 1; attempt <= MAX_REMEDIATION_ATTEMPTS; attempt += 1) {
+                const intentPath = remediationIntentPath(policy.dedupeKey, attempt);
+                const droppedPath = remediationDroppedPath(policy.dedupeKey, attempt);
+                if (await readImmutableJson(ctx, droppedPath))
+                    continue;
+                const claimed = await claimImmutableJson(ctx, intentPath, {
+                    kind: 'feature-guardian:remediation-intent',
+                    version: 1,
+                    repository: policy.repository,
+                    dedupeKey: policy.dedupeKey,
+                    bodyRevision,
+                    ...(attempt === 1 ? {} : { attempt }),
+                });
+                if (!claimed) {
+                    if (await readImmutableJson(ctx, droppedPath))
+                        continue;
+                    throw new Error('GitHub remediation submission is pending provider correlation; refusing a duplicate issue');
+                }
+                const created = await client.createIssue({
+                    owner,
+                    repo,
+                    title: policy.title,
+                    body: policy.body,
+                    labels: policy.labels,
+                });
+                if (created.status === 'dropped') {
+                    await appendImmutableJson(ctx, droppedPath, {
+                        kind: 'feature-guardian:remediation-drop',
+                        version: 1,
+                        repository: policy.repository,
+                        dedupeKey: policy.dedupeKey,
+                        attempt,
+                        reason: created.reason ?? 'provider dropped the remediation draft',
+                    });
+                    throw new Error('GitHub remediation issue create was dropped before provider admission');
+                }
+                if (created.status !== 'confirmed' || !created.url) {
+                    throw new Error(`GitHub remediation issue create was ${created.status}, not provider-confirmed`);
+                }
+                const number = issueNumberFromCreated(created.id, created.url);
+                if (!number)
+                    throw new Error('GitHub remediation issue receipt is missing its issue number');
+                const receipt = {
+                    repository: policy.repository,
+                    number,
+                    url: created.url,
+                    dedupeKey: policy.dedupeKey,
+                };
+                await appendImmutableJson(ctx, receiptPath, { ...receipt, bodyRevision });
+                return receipt;
+            }
+            throw new Error('GitHub remediation retry limit was exhausted after provider drops');
+        },
+    };
+}
+export function remediationMarker(dedupeKey) {
+    return `<!-- feature-guardian-remediation:${dedupeKey} -->`;
+}
+function remediationIntentPath(dedupeKey, attempt) {
+    const identity = attempt === 1 ? `intent:${dedupeKey}` : `intent:${dedupeKey}:${attempt}`;
+    return `${GUARDIAN_REMEDIATIONS_PATH}/${createHash('sha256').update(identity).digest('hex')}.json`;
+}
+function remediationDroppedPath(dedupeKey, attempt) {
+    return `${GUARDIAN_REMEDIATIONS_PATH}/${createHash('sha256').update(`drop:${dedupeKey}:${attempt}`).digest('hex')}.json`;
+}
+function remediationReceiptPath(dedupeKey) {
+    return `${GUARDIAN_REMEDIATIONS_PATH}/${createHash('sha256').update(`receipt:${dedupeKey}`).digest('hex')}.json`;
+}
+async function updateExistingIssueEvidence(ctx, client, owner, repo, issueNumber, policy) {
+    const bodyRevision = guardianContentRevision(policy.body);
+    const marker = `<!-- feature-guardian-evidence:${bodyRevision} -->`;
+    const ledgerKey = `${policy.dedupeKey}:${bodyRevision}`;
+    const receiptPath = `${GUARDIAN_REMEDIATIONS_PATH}/${createHash('sha256').update(`update-receipt:${ledgerKey}`).digest('hex')}.json`;
+    if (await readImmutableJson(ctx, receiptPath))
+        return;
+    const comments = await client['issue-comments'].list({
+        owner,
+        repo,
+        issueNumber,
+    });
+    if (comments.map(unwrapProviderRecord).some((comment) => providerText(comment.body).includes(marker))) {
+        await appendImmutableJson(ctx, receiptPath, { issueNumber, bodyRevision });
+        return;
+    }
+    for (let attempt = 1; attempt <= MAX_REMEDIATION_ATTEMPTS; attempt += 1) {
+        const suffix = attempt === 1 ? '' : `:${attempt}`;
+        const intentPath = `${GUARDIAN_REMEDIATIONS_PATH}/${createHash('sha256').update(`update-intent:${ledgerKey}${suffix}`).digest('hex')}.json`;
+        const droppedPath = `${GUARDIAN_REMEDIATIONS_PATH}/${createHash('sha256').update(`update-drop:${ledgerKey}:${attempt}`).digest('hex')}.json`;
+        if (await readImmutableJson(ctx, droppedPath))
+            continue;
+        const claimed = await claimImmutableJson(ctx, intentPath, {
+            issueNumber,
+            bodyRevision,
+            ...(attempt === 1 ? {} : { attempt }),
+        });
+        if (!claimed) {
+            if (await readImmutableJson(ctx, droppedPath))
+                continue;
+            throw new Error('GitHub remediation evidence update is pending; refusing a duplicate comment');
+        }
+        const updated = await client.comment({ owner, repo, number: issueNumber }, `${marker}\n${policy.body}`);
+        if (updated.status === 'dropped') {
+            await appendImmutableJson(ctx, droppedPath, {
+                issueNumber,
+                bodyRevision,
+                attempt,
+                reason: updated.reason ?? 'provider dropped the evidence update',
+            });
+            throw new Error('GitHub remediation evidence update was dropped before provider admission');
+        }
+        if (updated.status !== 'confirmed') {
+            throw new Error(`GitHub remediation evidence update was ${updated.status}, not provider-confirmed`);
+        }
+        await appendImmutableJson(ctx, receiptPath, { issueNumber, bodyRevision });
+        return;
+    }
+    throw new Error('GitHub remediation evidence retry limit was exhausted after provider drops');
+}
+function parseDurableIssueReceipt(value, policy) {
+    const receipt = parseIssueReceipt(value);
+    if (receipt.repository !== policy.repository || receipt.dedupeKey !== policy.dedupeKey) {
+        throw new Error('durable guardian issue receipt does not match its policy');
+    }
+    return receipt;
+}
+async function listGithubIssues(ctx, client, owner, repo) {
+    const listed = await client.issues.list({ owner, repo });
+    const issues = listed.filter((value) => asRecord(value) !== undefined);
+    const root = `${ctx.sandbox.cwd}/github/repos/${owner}/${repo}/issues`;
+    const rawIndex = await readOptionalSandboxFile(ctx, `${root}/_index.json`);
+    if (!rawIndex)
+        return issues;
+    const index = JSON.parse(rawIndex);
+    if (!Array.isArray(index))
+        throw new Error('guardian GitHub issue index is malformed');
+    for (const entry of index) {
+        const item = asRecord(entry);
+        const number = providerNumber(item?.number) ?? providerNumber(item?.id);
+        const title = providerText(item?.title);
+        if (!number || !title)
+            continue;
+        const slug = title
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/gu, '-')
+            .replace(/^-|-$/gu, '');
+        const candidates = [
+            `${root}/${number}__${slug}/meta.json`,
+            `${root}/${number}/meta.json`,
+            `${root}/${number}.json`,
+        ];
+        for (const path of candidates) {
+            const raw = await readOptionalSandboxFile(ctx, path);
+            if (!raw)
+                continue;
+            const record = asRecord(JSON.parse(raw));
+            if (record)
+                issues.push(record);
+            break;
+        }
+    }
+    return issues;
+}
+async function readOptionalSandboxFile(ctx, path) {
+    try {
+        return await ctx.sandbox.readFile(path);
+    }
+    catch (error) {
+        const message = String(error);
+        if (message.includes('ENOENT') || message.includes('not found') || message.includes('No such file')) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function readImmutableJson(ctx, path) {
+    const credentials = ctx.credentials.tryRequire();
+    let content;
+    if (credentials) {
+        const client = relayfileClient(credentials.relayfile);
+        const file = await withDeadline('guardian immutable ledger read', GUARDIAN_STATE_TIMEOUT_MS, (signal) => readExactFile(client, credentials.relayfile.workspaceId, path, signal));
+        content = file?.content;
+    }
+    else if (ctx.agent.id === 'sim-agent' && ctx.deployment.id === 'sim-deployment') {
+        try {
+            content = await ctx.files.read(path);
+        }
+        catch (error) {
+            if (!String(error).includes('ENOENT'))
+                throw error;
+        }
+    }
+    else {
+        throw new Error('exact Relayfile credentials are required for guardian remediation ledger');
+    }
+    if (content === undefined)
+        return null;
+    assertBoundedContent(content, 'guardian immutable ledger');
+    return JSON.parse(content);
+}
+async function appendImmutableJson(ctx, path, value) {
+    const content = `${JSON.stringify(value)}\n`;
+    assertBoundedContent(content, 'guardian immutable ledger');
+    const existing = await readImmutableJson(ctx, path);
+    if (existing !== null) {
+        if (`${JSON.stringify(existing)}\n` !== content) {
+            throw new Error('immutable guardian ledger entry already differs');
+        }
+        return;
+    }
+    const credentials = ctx.credentials.tryRequire();
+    if (credentials) {
+        const client = relayfileClient(credentials.relayfile);
+        try {
+            await withDeadline('guardian immutable ledger append', GUARDIAN_STATE_TIMEOUT_MS, (signal) => writeExactFile(client, credentials.relayfile.workspaceId, path, '0', content, signal));
+        }
+        catch (error) {
+            if (!(error instanceof RevisionConflictError) &&
+                !(error instanceof RelayFileApiError && error.status === 409))
+                throw error;
+        }
+    }
+    else if (ctx.agent.id === 'sim-agent' && ctx.deployment.id === 'sim-deployment') {
+        await ctx.files.write(path, content);
+    }
+    else {
+        throw new Error('exact Relayfile credentials are required for guardian remediation ledger');
+    }
+    const readBack = await readImmutableJson(ctx, path);
+    if (readBack === null || `${JSON.stringify(readBack)}\n` !== content) {
+        throw new Error('guardian immutable ledger read-back did not match');
+    }
+}
+/** Atomically claim one immutable provider submission. Only the CAS winner may write. */
+async function claimImmutableJson(ctx, path, value) {
+    const content = `${JSON.stringify(value)}\n`;
+    assertBoundedContent(content, 'guardian immutable claim');
+    const existing = await readImmutableJson(ctx, path);
+    if (existing !== null) {
+        if (`${JSON.stringify(existing)}\n` !== content) {
+            throw new Error('immutable guardian claim already differs');
+        }
+        return false;
+    }
+    const credentials = ctx.credentials.tryRequire();
+    if (credentials) {
+        const client = relayfileClient(credentials.relayfile);
+        try {
+            await withDeadline('guardian immutable claim', GUARDIAN_STATE_TIMEOUT_MS, (signal) => writeExactFile(client, credentials.relayfile.workspaceId, path, '0', content, signal));
+        }
+        catch (error) {
+            if (!(error instanceof RevisionConflictError) &&
+                !(error instanceof RelayFileApiError && error.status === 409))
+                throw error;
+            const winner = await readImmutableJson(ctx, path);
+            if (winner === null || `${JSON.stringify(winner)}\n` !== content) {
+                throw new Error('guardian immutable claim conflict did not match the winning intent');
+            }
+            return false;
+        }
+    }
+    else if (ctx.agent.id === 'sim-agent' && ctx.deployment.id === 'sim-deployment') {
+        const claimOwner = ctx.files;
+        const claims = PREVIEW_IMMUTABLE_CLAIMS.get(claimOwner) ?? new Set();
+        if (claims.has(path))
+            return false;
+        claims.add(path);
+        PREVIEW_IMMUTABLE_CLAIMS.set(claimOwner, claims);
+        await ctx.files.write(path, content);
+    }
+    else {
+        throw new Error('exact Relayfile credentials are required for guardian remediation claims');
+    }
+    const readBack = await readImmutableJson(ctx, path);
+    if (readBack === null || `${JSON.stringify(readBack)}\n` !== content) {
+        throw new Error('guardian immutable claim read-back did not match');
+    }
+    return true;
+}
+export function slackThreadBacklink(channelId, threadTs) {
+    return `https://slack.com/archives/${channelId}/p${threadTs.replace('.', '')}`;
+}
+async function postThreadReply(createSlackClient, record, text, idempotencyKey) {
+    const client = createSlackClient({
+        writebackTimeoutMs: GUARDIAN_WRITEBACK_TIMEOUT_MS,
+        writebackPollMs: GUARDIAN_WRITEBACK_POLL_MS,
+    });
+    const result = await client.replies.write({ channelId: record.channelId, messageTs: record.threadTs }, { text, thread_ts: record.threadTs, idempotencyKey });
+    return requireSlackReceiptTs(result);
+}
+function requireSlackReceiptTs(result) {
+    if (result.deliveryStatus && result.deliveryStatus !== 'confirmed') {
+        throw new Error(`guardian Slack reply was ${result.deliveryStatus}, not provider-confirmed`);
+    }
+    const receipt = asRecord(result.receipt);
+    const externalId = nonEmptyString(receipt?.externalId);
+    const fallbackTs = nonEmptyString(receipt?.ts);
+    const ts = externalId && /^\d+\.\d+$/u.test(externalId) ? externalId : fallbackTs;
+    if (!ts || !/^\d+\.\d+$/u.test(ts)) {
+        throw new Error('guardian Slack reply did not receive a provider timestamp');
+    }
+    return ts;
+}
+function confirmationRecord(record, turn, timestamp) {
+    if (!record.confirmationBasis) {
+        throw new Error('guardian confirmation record is missing its confirmation basis');
+    }
+    const evidence = record.evidence;
+    const commands = evidence.flatMap((entry) => entry.commands ?? []);
+    const tests = evidence.reduce((total, entry) => ({
+        passed: total.passed + (entry.tests?.passed ?? 0),
+        failed: total.failed + (entry.tests?.failed ?? 0),
+    }), { passed: 0, failed: 0 });
+    return {
+        kind: 'feature-guardian:confirmation',
+        version: 1,
+        featureId: record.feature.id,
+        manifestRevision: record.manifestRevision,
+        manifestVersion: record.manifestVersion,
+        procedureRevision: record.procedureRevision,
+        generation: record.generation,
+        result: 'confirmed',
+        ...(turn.actorId ? { actor: { id: turn.actorId } } : {}),
+        verifier: record.confirmationBasis.verifier,
+        timestamp,
+        evidence,
+        commands,
+        tests,
+        slack: {
+            channelId: record.channelId,
+            threadTs: record.threadTs,
+            questionTs: record.threadTs,
+        },
+    };
+}
+function parseConversationState(value) {
+    const root = asRecord(value);
+    if (!root || root.kind !== 'feature-guardian:conversations' || root.version !== 1) {
+        throw new Error('guardian conversation state kind/version is invalid');
+    }
+    if (!Array.isArray(root.records) || root.records.length > MAX_CONVERSATIONS) {
+        throw new Error('guardian conversation state records are invalid');
+    }
+    const records = root.records.map(parseConversationRecord);
+    if (new Set(records.map((record) => record.id)).size !== records.length) {
+        throw new Error('guardian conversation state contains duplicate records');
+    }
+    return { kind: 'feature-guardian:conversations', version: 1, records };
+}
+function parseConversationRecord(value) {
+    const record = asRecord(value);
+    if (!record)
+        throw new Error('guardian conversation record must be an object');
+    const feature = parseFeatureSnapshot(record.feature);
+    const status = record.status;
+    if (!isConversationStatus(status))
+        throw new Error('guardian conversation status is invalid');
+    const seenEventIds = stringArray(record.seenEventIds, MAX_SEEN_EVENTS, 'seen event ids');
+    const evidence = evidenceArray(record.evidence);
+    const turnCount = record.turnCount;
+    if (!Number.isSafeInteger(turnCount) || turnCount < 0 || turnCount > MAX_TURNS) {
+        throw new Error('guardian conversation turn count is invalid');
+    }
+    const clarificationCount = record.clarificationCount;
+    if (!Number.isSafeInteger(clarificationCount) ||
+        clarificationCount < 0 ||
+        clarificationCount > turnCount) {
+        throw new Error('guardian conversation clarification count is invalid');
+    }
+    const parsed = {
+        id: requireString(record.id, 'conversation id'),
+        feature,
+        manifestRevision: requireString(record.manifestRevision, 'manifest revision'),
+        manifestVersion: requireString(record.manifestVersion, 'manifest version'),
+        procedureRevision: requireString(record.procedureRevision, 'procedure revision'),
+        generation: requirePositiveInteger(record.generation, 'generation'),
+        channelId: requireString(record.channelId, 'channel id'),
+        threadTs: requireSlackTs(record.threadTs, 'thread ts'),
+        askedAt: requireTimestamp(record.askedAt, 'askedAt'),
+        status,
+        turnCount: turnCount,
+        clarificationCount: clarificationCount,
+        seenEventIds,
+        evidence,
+        updatedAt: requireTimestamp(record.updatedAt, 'updatedAt'),
+    };
+    if (record.pending !== undefined)
+        parsed.pending = parsePending(record.pending);
+    if (record.confirmationBasis !== undefined) {
+        parsed.confirmationBasis = parseConfirmationBasis(record.confirmationBasis);
+    }
+    if (record.confirmationPath !== undefined) {
+        parsed.confirmationPath = requireString(record.confirmationPath, 'confirmation path');
+    }
+    if (record.issue !== undefined)
+        parsed.issue = parseIssueReceipt(record.issue);
+    if (record.finalReplyTs !== undefined) {
+        parsed.finalReplyTs = requireSlackTs(record.finalReplyTs, 'final reply ts');
+    }
+    if (record.lastProcessedEventOrder !== undefined) {
+        parsed.lastProcessedEventOrder = requireEventOrder(record.lastProcessedEventOrder, 'last processed event order');
+    }
+    if (guardianConversationId(parsed) !== parsed.id) {
+        throw new Error('guardian conversation record identity is invalid');
+    }
+    if (isTerminal(parsed.status) && parsed.pending) {
+        throw new Error('terminal guardian conversation cannot retain a pending turn');
+    }
+    if ((parsed.status === 'asked' || parsed.status === 'discussing') && parsed.pending) {
+        throw new Error(`guardian ${parsed.status} conversation cannot retain a pending turn`);
+    }
+    if (isTerminal(parsed.status) && !parsed.finalReplyTs) {
+        throw new Error('terminal guardian conversation requires a provider-confirmed final reply');
+    }
+    if (['verifying', 'confirmation-recorded', 'remediation-recorded', 'deferred-recorded'].includes(parsed.status) && !parsed.pending) {
+        throw new Error(`guardian ${parsed.status} conversation requires a pending turn`);
+    }
+    if ((parsed.status === 'remediation-recorded' || parsed.status === 'remediation-open') &&
+        !parsed.issue) {
+        throw new Error(`guardian ${parsed.status} conversation requires an issue receipt`);
+    }
+    if (parsed.status === 'confirmed' && !parsed.confirmationPath) {
+        throw new Error('confirmed guardian conversation requires a confirmation path');
+    }
+    if ((parsed.status === 'confirmation-recorded' || parsed.status === 'confirmed') &&
+        !parsed.confirmationBasis) {
+        throw new Error(`guardian ${parsed.status} conversation requires a confirmation basis`);
+    }
+    if (parsed.confirmationBasis &&
+        parsed.status !== 'confirmation-recorded' &&
+        parsed.status !== 'confirmed') {
+        throw new Error('guardian confirmation basis is invalid for the conversation status');
+    }
+    if (parsed.status === 'confirmation-recorded' && parsed.pending && parsed.confirmationBasis) {
+        if (parsed.confirmationBasis.kind === 'actor' &&
+            (parsed.pending.response !== 'affirmative' ||
+                parsed.pending.actorId !== parsed.confirmationBasis.verifier ||
+                parsed.pending.evidence?.result !== 'positive')) {
+            throw new Error('guardian actor confirmation basis is inconsistent with its pending turn');
+        }
+        if (parsed.confirmationBasis.kind === 'procedure' &&
+            (parsed.pending.verification?.outcome !== 'passed' ||
+                parsed.pending.verification.verifier !== parsed.confirmationBasis.verifier ||
+                (parsed.pending.verification.tests?.failed ?? 0) !== 0)) {
+            throw new Error('guardian procedure confirmation basis is inconsistent with its pending turn');
+        }
+    }
+    if (parsed.status === 'confirmed' && parsed.confirmationBasis) {
+        const matchingEvidence = parsed.evidence.some((entry) => parsed.confirmationBasis?.kind === 'actor'
+            ? entry.source === 'actor' && entry.result === 'positive'
+            : entry.source === 'procedure' &&
+                entry.result === 'positive' &&
+                (entry.tests?.failed ?? 0) === 0);
+        if (!matchingEvidence) {
+            throw new Error('confirmed guardian conversation has no evidence for its confirmation basis');
+        }
+    }
+    if (parsed.confirmationPath &&
+        parsed.status !== 'confirmation-recorded' &&
+        parsed.status !== 'confirmed') {
+        throw new Error('guardian confirmation path is invalid for the conversation status');
+    }
+    if (parsed.issue &&
+        parsed.status !== 'remediation-recorded' &&
+        parsed.status !== 'remediation-open') {
+        throw new Error('guardian issue receipt is invalid for the conversation status');
+    }
+    return parsed;
+}
+function parseConfirmationRecord(value) {
+    const record = asRecord(value);
+    if (!record || record.kind !== 'feature-guardian:confirmation' || record.version !== 1) {
+        throw new Error('guardian confirmation kind/version is invalid');
+    }
+    const actor = asRecord(record.actor);
+    const slack = asRecord(record.slack);
+    const tests = asRecord(record.tests);
+    if (record.result !== 'confirmed' || !slack || !tests) {
+        throw new Error('guardian confirmation result/evidence is invalid');
+    }
+    const failed = requireNonNegativeInteger(tests.failed, 'failed tests');
+    if (failed !== 0)
+        throw new Error('confirmed guardian evidence cannot contain failed tests');
+    return {
+        kind: 'feature-guardian:confirmation',
+        version: 1,
+        featureId: requireString(record.featureId, 'feature id'),
+        manifestRevision: requireString(record.manifestRevision, 'manifest revision'),
+        manifestVersion: requireString(record.manifestVersion, 'manifest version'),
+        procedureRevision: requireString(record.procedureRevision, 'procedure revision'),
+        generation: requirePositiveInteger(record.generation, 'generation'),
+        result: 'confirmed',
+        ...(actor ? { actor: { id: requireString(actor.id, 'actor id') } } : {}),
+        verifier: requireString(record.verifier, 'verifier'),
+        timestamp: requireTimestamp(record.timestamp, 'timestamp'),
+        evidence: evidenceArray(record.evidence),
+        commands: stringArray(record.commands, 128, 'commands'),
+        tests: {
+            passed: requireNonNegativeInteger(tests.passed, 'passed tests'),
+            failed,
+        },
+        slack: {
+            channelId: requireString(slack.channelId, 'Slack channel id'),
+            threadTs: requireSlackTs(slack.threadTs, 'Slack thread ts'),
+            questionTs: requireSlackTs(slack.questionTs, 'Slack question ts'),
+        },
+    };
+}
+function parseConfirmationBasis(value) {
+    const basis = asRecord(value);
+    if (!basis || (basis.kind !== 'actor' && basis.kind !== 'procedure')) {
+        throw new Error('guardian confirmation basis is invalid');
+    }
+    return { kind: basis.kind, verifier: requireString(basis.verifier, 'confirmation verifier') };
+}
+function assertConversationTransition(previous, next) {
+    if (!previous)
+        return;
+    const nextById = new Map(next.records.map((record) => [record.id, record]));
+    const removed = previous.records.filter((record) => !nextById.has(record.id));
+    if (removed.some((record) => !isTerminal(record.status))) {
+        throw new Error('guardian conversation records are append-only except bounded terminal pruning');
+    }
+    for (const prior of previous.records) {
+        const current = nextById.get(prior.id);
+        if (!current)
+            continue;
+        if (!sameQuestion(prior, current)) {
+            throw new Error('guardian conversation question identity is immutable');
+        }
+        if (isTerminal(prior.status) && JSON.stringify(prior) !== JSON.stringify(current)) {
+            throw new Error('terminal guardian conversation records are immutable');
+        }
+        if (!prior.seenEventIds.every((id) => current.seenEventIds.includes(id))) {
+            throw new Error('guardian conversation seen-event history cannot regress');
+        }
+        if (JSON.stringify(current.evidence.slice(0, prior.evidence.length)) !==
+            JSON.stringify(prior.evidence)) {
+            throw new Error('guardian conversation evidence is append-only');
+        }
+        if (prior.confirmationPath !== undefined &&
+            current.confirmationPath !== prior.confirmationPath) {
+            throw new Error('guardian conversation confirmation path is immutable');
+        }
+        if (prior.confirmationBasis !== undefined &&
+            JSON.stringify(current.confirmationBasis) !== JSON.stringify(prior.confirmationBasis)) {
+            throw new Error('guardian conversation confirmation basis is immutable');
+        }
+        if (prior.issue !== undefined && JSON.stringify(current.issue) !== JSON.stringify(prior.issue)) {
+            throw new Error('guardian conversation issue receipt is immutable');
+        }
+        if (current.turnCount < prior.turnCount) {
+            throw new Error('guardian conversation turn count cannot regress');
+        }
+        if (current.clarificationCount < prior.clarificationCount) {
+            throw new Error('guardian conversation clarification count cannot regress');
+        }
+        if (prior.lastProcessedEventOrder &&
+            (!current.lastProcessedEventOrder ||
+                current.lastProcessedEventOrder < prior.lastProcessedEventOrder)) {
+            throw new Error('guardian conversation event-order watermark cannot regress');
+        }
+        if (!validStatusTransition(prior.status, current.status)) {
+            throw new Error(`invalid guardian conversation transition ${prior.status} -> ${current.status}`);
+        }
+    }
+}
+function validStatusTransition(previous, next) {
+    if (previous === next)
+        return true;
+    const allowed = {
+        asked: ['discussing', 'verifying', 'confirmation-recorded', 'deferred-recorded'],
+        discussing: ['discussing', 'verifying', 'confirmation-recorded', 'deferred-recorded'],
+        verifying: ['discussing', 'confirmation-recorded', 'remediation-recorded', 'deferred-recorded'],
+        'confirmation-recorded': ['confirmed'],
+        'remediation-recorded': ['remediation-open'],
+        'deferred-recorded': ['deferred'],
+        confirmed: [],
+        'remediation-open': [],
+        deferred: [],
+    };
+    return allowed[previous].includes(next);
+}
+function parseFeatureSnapshot(value) {
+    const feature = asRecord(value);
+    if (!feature)
+        throw new Error('guardian feature snapshot must be an object');
+    const tier = requirePositiveInteger(feature.tier, 'feature tier');
+    if (tier > 6)
+        throw new Error('guardian feature tier is invalid');
+    return {
+        id: requireString(feature.id, 'feature id'),
+        name: requireString(feature.name, 'feature name'),
+        category: requireString(feature.category, 'feature category'),
+        ...(nonEmptyString(feature.cli) ? { cli: nonEmptyString(feature.cli) } : {}),
+        ...(nonEmptyString(feature.api) ? { api: nonEmptyString(feature.api) } : {}),
+        description: requireString(feature.description, 'feature description'),
+        locations: stringArray(feature.locations, 32, 'feature locations'),
+        procedure: requireString(feature.procedure, 'feature procedure'),
+        tier,
+        criticality: requireString(feature.criticality, 'feature criticality'),
+    };
+}
+function parsePending(value) {
+    const pending = asRecord(value);
+    if (!pending || !isResponseKind(pending.response)) {
+        throw new Error('guardian pending turn is invalid');
+    }
+    return {
+        eventId: requireString(pending.eventId, 'event id'),
+        eventOrder: requireEventOrder(pending.eventOrder, 'pending event order'),
+        eventOccurredAt: requireTimestamp(pending.eventOccurredAt, 'event occurredAt'),
+        actorId: requireString(pending.actorId, 'actor id'),
+        response: pending.response,
+        text: typeof pending.text === 'string' ? bounded(pending.text, 4_000) : '',
+        ...(nonEmptyString(pending.reaction) ? { reaction: nonEmptyString(pending.reaction) } : {}),
+        ...(pending.evidence !== undefined ? { evidence: parseEvidence(pending.evidence) } : {}),
+        ...(pending.verification !== undefined
+            ? { verification: parseProcedureResult(pending.verification) }
+            : {}),
+        ...(isDefectKind(pending.defectKind) ? { defectKind: pending.defectKind } : {}),
+    };
+}
+function parseProcedureResult(value) {
+    const result = asRecord(value);
+    const evidence = parseEvidence(value);
+    if (evidence.source !== 'procedure' ||
+        !['passed', 'failed', 'skip', 'manual'].includes(String(result?.outcome))) {
+        throw new Error('guardian procedure result is invalid');
+    }
+    const outcome = result?.outcome;
+    const expectedResult = {
+        passed: 'positive',
+        failed: 'negative',
+        skip: 'skip',
+        manual: 'manual',
+    };
+    if (evidence.result !== expectedResult[outcome]) {
+        throw new Error('guardian procedure outcome/result is inconsistent');
+    }
+    return {
+        ...evidence,
+        source: 'procedure',
+        outcome,
+        verifier: requireString(result?.verifier, 'procedure verifier'),
+    };
+}
+function parseIssueReceipt(value) {
+    const issue = asRecord(value);
+    if (!issue)
+        throw new Error('guardian issue receipt is invalid');
+    return {
+        repository: requireString(issue.repository, 'issue repository'),
+        number: requirePositiveInteger(issue.number, 'issue number'),
+        url: requireString(issue.url, 'issue url'),
+        dedupeKey: requireString(issue.dedupeKey, 'issue dedupe key'),
+    };
+}
+function evidenceArray(value) {
+    if (!Array.isArray(value) || value.length > MAX_EVIDENCE_ITEMS) {
+        throw new Error('guardian evidence is invalid');
+    }
+    return value.map(parseEvidence);
+}
+function parseEvidence(value) {
+    const evidence = asRecord(value);
+    if (!evidence ||
+        !['actor', 'procedure', 'system'].includes(String(evidence.source)) ||
+        !['positive', 'negative', 'skip', 'manual', 'unknown'].includes(String(evidence.result))) {
+        throw new Error('guardian evidence item is invalid');
+    }
+    const tests = asRecord(evidence.tests);
+    return {
+        source: evidence.source,
+        result: evidence.result,
+        summary: requireString(evidence.summary, 'evidence summary'),
+        ...(evidence.commands !== undefined
+            ? { commands: stringArray(evidence.commands, 128, 'evidence commands') }
+            : {}),
+        ...(evidence.positiveAssertions !== undefined
+            ? {
+                positiveAssertions: stringArray(evidence.positiveAssertions, 128, 'positive assertions'),
+            }
+            : {}),
+        ...(evidence.negativeAssertions !== undefined
+            ? {
+                negativeAssertions: stringArray(evidence.negativeAssertions, 128, 'negative assertions'),
+            }
+            : {}),
+        ...(tests
+            ? {
+                tests: {
+                    passed: requireNonNegativeInteger(tests.passed, 'passed tests'),
+                    failed: requireNonNegativeInteger(tests.failed, 'failed tests'),
+                },
+            }
+            : {}),
+        ...(evidence.cleanup !== undefined
+            ? { cleanup: stringArray(evidence.cleanup, 32, 'cleanup evidence') }
+            : {}),
+    };
+}
+function findCorrelatedConversation(state, event) {
+    const candidates = state.records.filter((record) => record.channelId === event.channelId &&
+        record.threadTs === event.threadTs &&
+        (!event.isReaction || event.messageTs === record.threadTs));
+    return candidates.length === 1 ? candidates[0] : undefined;
+}
+function findSlackPayload(root) {
+    if (!root)
+        return undefined;
+    const queue = [root];
+    const seen = new Set();
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        if (nonEmptyString(current.channel) ||
+            nonEmptyString(asRecord(current.item)?.channel) ||
+            nonEmptyString(current.thread_ts)) {
+            return current;
+        }
+        for (const key of ['payload', 'event', 'message', 'data', 'resource', 'record']) {
+            const nested = asRecord(current[key]);
+            if (nested)
+                queue.push(nested);
+        }
+    }
+    return undefined;
+}
+function channelFromPath(path) {
+    const encoded = path?.match(/^\/slack\/channels\/([^/]+)/u)?.[1];
+    return encoded?.split('__')[0];
+}
+function messageTsFromPath(path) {
+    const match = path?.match(/\/messages\/([^/]+)(?:\/replies\/([^/.]+))?/u);
+    return (match?.[2] ?? match?.[1])?.replaceAll('_', '.');
+}
+function pendingTurn(parsed, response, evidence) {
+    return {
+        eventId: parsed.eventId,
+        eventOrder: parsed.eventOrder,
+        eventOccurredAt: parsed.occurredAt,
+        actorId: parsed.actorId,
+        response,
+        text: parsed.text,
+        ...(parsed.reaction ? { reaction: parsed.reaction } : {}),
+        evidence,
+    };
+}
+function emptyConversationState() {
+    return { kind: 'feature-guardian:conversations', version: 1, records: [] };
+}
+function retainConversationCapacity(records, incoming) {
+    let retained = [...records];
+    for (;;) {
+        const candidate = {
+            kind: 'feature-guardian:conversations',
+            version: 1,
+            records: [...retained, incoming],
+        };
+        const fitsCount = candidate.records.length <= MAX_CONVERSATIONS;
+        const fitsBytes = UTF8_ENCODER.encode(`${JSON.stringify(candidate)}\n`).byteLength <= MAX_STATE_BYTES;
+        if (fitsCount && fitsBytes)
+            return retained;
+        const removable = retained
+            .filter((record) => isTerminal(record.status))
+            .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt))[0];
+        if (!removable) {
+            throw new Error('guardian conversation state reached its bounded active-record limit');
+        }
+        retained = retained.filter((record) => record.id !== removable.id);
+    }
+}
+function replaceRecord(state, id, next) {
+    return {
+        ...state,
+        records: state.records.map((record) => (record.id === id ? next : record)),
+    };
+}
+function requireRecordById(state, id) {
+    const record = state.records.find((candidate) => candidate.id === id);
+    if (!record)
+        throw new Error('guardian conversation disappeared after checkpoint');
+    return record;
+}
+function sameQuestion(left, right) {
+    return JSON.stringify({
+        feature: left.feature,
+        manifestRevision: left.manifestRevision,
+        manifestVersion: left.manifestVersion,
+        procedureRevision: left.procedureRevision,
+        generation: left.generation,
+        channelId: left.channelId,
+        threadTs: left.threadTs,
+        askedAt: left.askedAt,
+    }) === JSON.stringify({
+        feature: right.feature,
+        manifestRevision: right.manifestRevision,
+        manifestVersion: right.manifestVersion,
+        procedureRevision: right.procedureRevision,
+        generation: right.generation,
+        channelId: right.channelId,
+        threadTs: right.threadTs,
+        askedAt: right.askedAt,
+    });
+}
+function appendSeen(existing, eventId) {
+    if (existing.includes(eventId))
+        return existing;
+    if (existing.length >= MAX_SEEN_EVENTS) {
+        throw new Error('guardian conversation seen-event history reached its bounded limit');
+    }
+    return [...existing, eventId];
+}
+function appendEvidence(existing, evidence) {
+    if (!evidence)
+        return existing;
+    if (existing.length >= MAX_EVIDENCE_ITEMS) {
+        throw new Error('guardian conversation evidence reached its bounded limit');
+    }
+    return [...existing, evidence];
+}
+function previewRevision(state) {
+    return `preview:${guardianContentRevision(JSON.stringify(state))}`;
+}
+function isTerminal(status) {
+    return status === 'confirmed' || status === 'remediation-open' || status === 'deferred';
+}
+function isConversationStatus(value) {
+    return [
+        'asked',
+        'discussing',
+        'verifying',
+        'confirmation-recorded',
+        'remediation-recorded',
+        'deferred-recorded',
+        'confirmed',
+        'remediation-open',
+        'deferred',
+    ].includes(String(value));
+}
+function isResponseKind(value) {
+    return ['affirmative', 'failure', 'untested', 'ambiguous', 'deferred'].includes(String(value));
+}
+function isDefectKind(value) {
+    return ['implementation', 'test', 'manifest', 'procedure', 'documentation'].includes(String(value));
+}
+function shortRevision(revision) {
+    return revision.replace(/^sha256:/u, '').slice(0, 12);
+}
+function hasActorConfirmationEvidence(text) {
+    return /\b(tested|verified|confirmed)\b/iu.test(text) &&
+        /\b(works?|working|passes?|passed|expected|good)\b/iu.test(text);
+}
+function formatEvidenceForSlack(evidence) {
+    return [
+        evidence.summary,
+        ...(evidence.positiveAssertions?.map((value) => `PASS: ${value}`) ?? []),
+        ...(evidence.negativeAssertions?.map((value) => `FAIL: ${value}`) ?? []),
+        ...(evidence.tests ? [`Tests: ${evidence.tests.passed} passed, ${evidence.tests.failed} failed.`] : []),
+        ...(evidence.cleanup?.map((value) => `Cleanup: ${value}`) ?? []),
+    ].join(' ');
+}
+function resolvedInput(ctx, name) {
+    const spec = ctx.persona?.inputSpecs?.[name];
+    const value = process.env[spec?.env ?? name] ?? ctx.persona?.inputs?.[name] ?? spec?.default;
+    return nonEmptyString(value);
+}
+function remediationBodyHasMarker(body, key) {
+    return body.includes(remediationMarker(key));
+}
+function unwrapProviderRecord(value) {
+    return asRecord(value.payload) ?? asRecord(value.data) ?? value;
+}
+function providerText(value) {
+    return typeof value === 'string' ? value : '';
+}
+function providerNumber(value) {
+    const parsed = typeof value === 'number' ? value : Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+function issueNumberFromCreated(id, url) {
+    return providerNumber(id) ?? providerNumber(url.match(/\/issues\/(\d+)(?:$|[?#])/u)?.[1]);
+}
+function relayfileClient(credentials, fetchImpl) {
+    return new RelayFileClient({
+        baseUrl: credentials.url,
+        token: credentials.token,
+        fetchImpl,
+        readCache: false,
+        retry: { maxRetries: 0 },
+    });
+}
+async function readExactFile(client, workspaceId, path, signal) {
+    let file;
+    try {
+        file = await client.readFile(workspaceId, path, `guardian-read-${randomUUID()}`, signal);
+    }
+    catch (error) {
+        if (error instanceof RelayFileApiError && error.status === 404)
+            return null;
+        throw error;
+    }
+    if (!file || file.path !== path || typeof file.content !== 'string') {
+        throw new Error('guardian exact read returned an invalid file');
+    }
+    const revision = nonEmptyString(file.revision);
+    if (!revision)
+        throw new Error('guardian exact read returned an invalid revision');
+    return { content: file.content, revision };
+}
+async function writeExactFile(client, workspaceId, path, baseRevision, content, signal) {
+    const correlationId = `guardian-write-${randomUUID()}`;
+    const queued = await client.writeFile({
+        workspaceId,
+        path,
+        baseRevision,
+        content,
+        contentType: 'application/json',
+        encoding: 'utf-8',
+        correlationId,
+        signal,
+    });
+    if (!queued || !nonEmptyString(queued.opId)) {
+        throw new Error('guardian exact write did not return an operation ID');
+    }
+    await waitForOperation(client, workspaceId, queued.opId, signal, correlationId);
+}
+async function waitForOperation(client, workspaceId, opId, signal, correlationId) {
+    for (;;) {
+        const operation = await client.getOp(workspaceId, opId, correlationId, signal);
+        if (operation?.status === 'succeeded')
+            return operation;
+        if (['failed', 'dead_lettered', 'canceled'].includes(String(operation?.status))) {
+            throw new Error(`guardian exact write ${operation?.status}`);
+        }
+        if (!['pending', 'running'].includes(String(operation?.status))) {
+            throw new Error('guardian exact write returned an invalid operation status');
+        }
+        await abortableDelay(GUARDIAN_WRITEBACK_POLL_MS, signal);
+    }
+}
+async function withDeadline(label, timeoutMs, operation) {
+    const controller = new AbortController();
+    let timeout;
+    const expired = new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+            controller.abort();
+            reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([operation(controller.signal), expired]);
+    }
+    finally {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+    }
+}
+function abortableDelay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(signal.reason);
+        };
+        const timeout = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function assertBoundedContent(content, label) {
+    if (UTF8_ENCODER.encode(content).byteLength > MAX_STATE_BYTES) {
+        throw new Error(`${label} exceeds size limit`);
+    }
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function requireString(value, field) {
+    const parsed = nonEmptyString(value);
+    if (!parsed || parsed.length > 8_192)
+        throw new Error(`guardian ${field} is invalid`);
+    return parsed;
+}
+function stringArray(value, max, field) {
+    if (!Array.isArray(value) || value.length > max)
+        throw new Error(`guardian ${field} is invalid`);
+    const parsed = value.map((entry) => requireString(entry, field));
+    if (new Set(parsed).size !== parsed.length && field === 'seen event ids') {
+        throw new Error(`guardian ${field} contains duplicates`);
+    }
+    return parsed;
+}
+function requirePositiveInteger(value, field) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`guardian ${field} is invalid`);
+    }
+    return value;
+}
+function requireNonNegativeInteger(value, field) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`guardian ${field} is invalid`);
+    }
+    return value;
+}
+function canonicalTimestamp(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const date = new Date(value);
+    return Number.isFinite(date.valueOf()) ? date.toISOString() : undefined;
+}
+function timestampFromSlackTs(value) {
+    if (!value || !/^\d+\.\d+$/u.test(value))
+        return undefined;
+    const seconds = Number(value);
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return undefined;
+    return new Date(seconds * 1_000).toISOString();
+}
+function slackTsOrder(value) {
+    const match = value.match(/^(\d+)\.(\d{1,9})$/u);
+    if (!match)
+        return '00000000000000000000.000000000';
+    return `${match[1].padStart(20, '0')}.${match[2].padEnd(9, '0')}`;
+}
+function requireTimestamp(value, field) {
+    const timestamp = canonicalTimestamp(value);
+    if (!timestamp || timestamp !== value)
+        throw new Error(`guardian ${field} is invalid`);
+    return timestamp;
+}
+function requireSlackTs(value, field) {
+    const ts = requireString(value, field);
+    if (!/^\d+\.\d+$/u.test(ts))
+        throw new Error(`guardian ${field} is invalid`);
+    return ts;
+}
+function requireEventOrder(value, field) {
+    const order = requireString(value, field);
+    // Event order is internal and compared lexicographically. Its exact shape
+    // is ISO timestamp + normalized provider ts + Slack message ts + stable
+    // response identity. Accept the prior three-part form so pre-upgrade state
+    // remains readable.
+    const match = order.match(/^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z):(?:(?:\d{20}\.\d{9}):)?\d+\.\d+:slack:[a-f0-9]{64}$/u);
+    if (!match || canonicalTimestamp(match[1]) !== match[1]) {
+        throw new Error(`guardian ${field} is invalid`);
+    }
+    return order;
+}
+function bounded(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+}
+// Retain a named predicate for issue adapters/tests without exporting provider internals.
+void remediationBodyHasMarker;
+//# sourceMappingURL=conversation.js.map