@ouro.bot/cli 0.1.0-alpha.83 → 0.1.0-alpha.831

package/dist/senses/telegram-admission.js

@@ -0,0 +1,718 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileTelegramAdmissionStore = exports.NEWLY_ADMITTED_ORIENTATION = exports.FIXED_ADMISSION_ACKNOWLEDGEMENT = void 0;
+exports.createTelegramAdmissionController = createTelegramAdmissionController;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const session_transaction_1 = require("../mind/session-transaction");
+const telegram_effect_adapter_1 = require("./telegram-effect-adapter");
+Object.defineProperty(exports, "FIXED_ADMISSION_ACKNOWLEDGEMENT", { enumerable: true, get: function () { return telegram_effect_adapter_1.FIXED_ADMISSION_ACKNOWLEDGEMENT; } });
+const telegram_client_1 = require("./telegram-client");
+exports.NEWLY_ADMITTED_ORIENTATION = {
+    kind: "newly_admitted",
+    instruction: "welcome_and_explain_capabilities",
+    attachmentsNeedResend: false,
+};
+const ACTIVE_STATUSES = new Set([
+    "pending", "approved", "friend_bound", "ingress_committed", "turn_queued",
+]);
+const TERMINAL_STATUSES = new Set([
+    "handled", "denied", "blocked", "expired", "collision", "indeterminate",
+]);
+const ADMISSION_ID = /^[a-f0-9]{20}$/u;
+const CANONICAL_ID = /^[1-9][0-9]*$/u;
+const KINSHIP = new Set(["brother", "sister", "sibling", "mother", "father", "parent", "son", "daughter", "aunt", "uncle", "cousin", "grandmother", "grandfather", "wife", "husband", "partner"]);
+function normalizeKinship(value) {
+    const normalized = value === "mom" || value === "mum" ? "mother"
+        : value === "dad" ? "father"
+            : value === "grandma" ? "grandmother"
+                : value === "grandpa" ? "grandfather"
+                    : value;
+    if (!KINSHIP.has(normalized))
+        throw new Error("Telegram admission kinship is invalid");
+    return normalized;
+}
+const DEFAULT_LIMITS = {
+    maxPendingContacts: 32,
+    maxTextBytes: 16 * 1024,
+    maxMessagesPerIdentity: 8,
+    maxMessagesPerWindow: 128,
+    rateWindowMs: 60_000,
+    maxTotalBytes: 256 * 1024,
+    retentionMs: 24 * 60 * 60 * 1_000,
+    retryCooldownMs: 5 * 60 * 1_000,
+    terminalRetentionMs: 7 * 24 * 60 * 60 * 1_000,
+    maxTerminalRecords: 256,
+};
+function admissionId(input) {
+    return crypto.createHash("sha256")
+        .update(`telegram-admission-v1\0${input.botId}\0${input.userId}\0${input.chatId}\0${input.updateId}`)
+        .digest("hex")
+        .slice(0, 20);
+}
+function digest(value) {
+    return crypto.createHash("sha256").update(value, "utf8").digest("hex");
+}
+function identity(record) {
+    return `${record.botId}:${record.userId}:${record.chatId}`;
+}
+function boundedLabel(value) {
+    return [...value.normalize("NFKC")].slice(0, 120).join("") || "(no Telegram label)";
+}
+function assertSafeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`Telegram admission ${label} is invalid`);
+}
+function assertCanonicalId(value, label) {
+    if (!CANONICAL_ID.test(value))
+        throw new Error(`Telegram admission ${label} is invalid`);
+}
+function validateRecord(value, expectedId) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Telegram admission record is invalid");
+    const record = value;
+    if (record.schemaVersion !== 1 || !ADMISSION_ID.test(record.id) || (expectedId !== undefined && record.id !== expectedId)
+        || !Number.isSafeInteger(record.revision) || record.revision < 0
+        || ![...ACTIVE_STATUSES, ...TERMINAL_STATUSES].includes(record.status)
+        || typeof record.botId !== "string" || typeof record.userId !== "string" || typeof record.chatId !== "string"
+        || !CANONICAL_ID.test(record.botId) || !CANONICAL_ID.test(record.userId) || !CANONICAL_ID.test(record.chatId)
+        || !Number.isSafeInteger(record.updateId) || record.updateId < 0
+        || !Number.isSafeInteger(record.messageId) || record.messageId < 1
+        || (record.quarantinedText !== null && typeof record.quarantinedText !== "string")
+        || typeof record.contentDigest !== "string" || !/^[a-f0-9]{64}$/u.test(record.contentDigest)
+        || typeof record.displayLabel !== "string" || [...record.displayLabel].length > 120
+        || typeof record.displayCode !== "string" || record.displayCode.length < 4 || record.displayCode.length > 32
+        || typeof record.hasAttachments !== "boolean"
+        || (record.ownerRelationship !== undefined && !KINSHIP.has(record.ownerRelationship))
+        || ![record.createdAt, record.updatedAt, record.expiresAt].every(Number.isSafeInteger)
+        || (record.friendId !== null && (typeof record.friendId !== "string" || !record.friendId))
+        || (record.acknowledgementArtifactId !== null && typeof record.acknowledgementArtifactId !== "string")
+        || (record.ownerCardArtifactId !== null && typeof record.ownerCardArtifactId !== "string")
+        || (record.ingressSessionKey !== null && (typeof record.ingressSessionKey !== "string" || record.ingressSessionKey.length < 1 || record.ingressSessionKey.length > 1_024))
+        || (record.ingressEventId !== null && (typeof record.ingressEventId !== "string" || !/^evt-[0-9]{6,}$/u.test(record.ingressEventId)))
+        || (record.ingressReference !== null && record.ingressReference !== `telegram-admission:${record.id}`)
+        || ([record.ingressSessionKey, record.ingressEventId, record.ingressReference].filter((entry) => entry !== null).length !== 0
+            && [record.ingressSessionKey, record.ingressEventId, record.ingressReference].some((entry) => entry === null))
+        || (TERMINAL_STATUSES.has(record.status) && record.quarantinedText !== null)) {
+        throw new Error("Telegram admission record is invalid");
+    }
+}
+function atomicWrite(filePath, value) {
+    const temporaryPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    const handle = fs.openSync(temporaryPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        fs.writeFileSync(handle, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        fs.fsyncSync(handle);
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+    fs.renameSync(temporaryPath, filePath);
+    fs.chmodSync(filePath, 0o600);
+    const directory = fs.openSync(path.dirname(filePath), fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    try {
+        fs.fsyncSync(directory);
+    }
+    finally {
+        fs.closeSync(directory);
+    }
+}
+function readBoundedPrivateJson(filePath, maxBytes, label) {
+    const handle = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+        const stat = fs.fstatSync(handle);
+        if (!stat.isFile() || stat.size < 2 || stat.size > maxBytes || (stat.mode & 0o777) !== 0o600) {
+            throw new Error(`Telegram admission ${label} is not a bounded private regular file`);
+        }
+        return JSON.parse(fs.readFileSync(handle, "utf8"));
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+}
+class FileTelegramAdmissionStore {
+    root;
+    now;
+    limits;
+    rootFd;
+    rootIdentity;
+    closed = false;
+    constructor(root, limits = {}, now = Date.now) {
+        this.root = root;
+        this.now = now;
+        this.limits = { ...DEFAULT_LIMITS, ...limits };
+        for (const [key, value] of Object.entries(this.limits)) {
+            if (!Number.isSafeInteger(value) || value < 1)
+                throw new Error(`Telegram admission ${key} must be a positive safe integer`);
+        }
+        if (fs.existsSync(root)) {
+            const stat = fs.lstatSync(root);
+            if (stat.isSymbolicLink())
+                throw new Error("Telegram admission root must not be a symbolic link");
+            if (!stat.isDirectory())
+                throw new Error("Telegram admission root must be a directory");
+        }
+        else
+            fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+        fs.chmodSync(root, 0o700);
+        const stat = fs.lstatSync(root);
+        /* v8 ignore next -- race defense: constructor-created/chmodded roots satisfy this unless another process swaps the path between syscalls @preserve */
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o777) !== 0o700)
+            throw new Error("Telegram admission root is unsafe");
+        this.rootFd = fs.openSync(root, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+        const pinned = fs.fstatSync(this.rootFd);
+        this.rootIdentity = { dev: pinned.dev, ino: pinned.ino };
+    }
+    assertRootIdentity() {
+        if (this.closed)
+            throw new Error("Telegram admission store is closed");
+        const pinned = fs.fstatSync(this.rootFd);
+        const current = fs.lstatSync(this.root);
+        if (!pinned.isDirectory() || !current.isDirectory() || current.isSymbolicLink()
+            || pinned.dev !== this.rootIdentity.dev || pinned.ino !== this.rootIdentity.ino
+            || current.dev !== this.rootIdentity.dev || current.ino !== this.rootIdentity.ino
+            || (current.mode & 0o777) !== 0o700)
+            throw new Error("Telegram admission root identity changed");
+    }
+    close() {
+        if (this.closed)
+            return;
+        fs.closeSync(this.rootFd);
+        this.closed = true;
+    }
+    filePath(id) {
+        if (!ADMISSION_ID.test(id))
+            throw new Error("Telegram admission id is invalid");
+        return path.join(this.root, `${id}.json`);
+    }
+    coordinationPath(id) {
+        return `${this.filePath(id)}.decision`;
+    }
+    selfHealthPath() {
+        return path.join(this.root, "self-health.json");
+    }
+    rateStatePath() {
+        return path.join(this.root, "rate-window.json");
+    }
+    globalCoordinationPath() {
+        return path.join(path.dirname(this.root), `.${path.basename(this.root)}-coordination`, "admission");
+    }
+    readRateState(now) {
+        let state = { version: 1, events: [] };
+        try {
+            const value = readBoundedPrivateJson(this.rateStatePath(), 256 * 1024, "rate state");
+            if (value.version !== 1 || !Array.isArray(value.events) || value.events.some((event) => !event
+                || !/^[a-f0-9]{64}$/u.test(event.identityDigest) || !/^[a-f0-9]{64}$/u.test(event.updateDigest)
+                || !Number.isSafeInteger(event.observedAt) || event.observedAt < 0))
+                throw new Error("invalid");
+            state = value;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw new Error("Telegram admission rate state is invalid", { cause: error });
+        }
+        state.events = state.events.filter((event) => event.observedAt > now - this.limits.rateWindowMs);
+        return state;
+    }
+    recordRateAttempt(input, now) {
+        this.assertRootIdentity();
+        const state = this.readRateState(now);
+        const identityDigest = digest(`identity\0${identity(input)}`);
+        const updateDigest = digest(`update\0${input.botId}\0${input.updateId}`);
+        if (!state.events.some((event) => event.updateDigest === updateDigest))
+            state.events.push({ identityDigest, updateDigest, observedAt: now });
+        const identityCount = state.events.filter((event) => event.identityDigest === identityDigest).length;
+        const overflow = identityCount > this.limits.maxMessagesPerIdentity || state.events.length > this.limits.maxMessagesPerWindow;
+        state.events = state.events
+            .sort((left, right) => left.observedAt - right.observedAt || left.updateDigest.localeCompare(right.updateDigest))
+            .slice(-(this.limits.maxMessagesPerWindow + 1));
+        atomicWrite(this.rateStatePath(), state);
+        this.assertRootIdentity();
+        return overflow;
+    }
+    compactTerminalRecords(records, now) {
+        const terminal = records.filter((record) => TERMINAL_STATUSES.has(record.status))
+            .sort((left, right) => right.updatedAt - left.updatedAt || left.id.localeCompare(right.id));
+        const retained = new Set(terminal
+            .filter((record) => record.updatedAt > now - this.limits.terminalRetentionMs)
+            .slice(0, this.limits.maxTerminalRecords)
+            .map((record) => record.id));
+        for (const record of terminal) {
+            if (!retained.has(record.id))
+                fs.unlinkSync(this.filePath(record.id));
+        }
+        this.assertRootIdentity();
+        return records.filter((record) => !TERMINAL_STATUSES.has(record.status) || retained.has(record.id));
+    }
+    read(id) {
+        this.assertRootIdentity();
+        const filePath = this.filePath(id);
+        const handle = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            const stat = fs.fstatSync(handle);
+            if (!stat.isFile() || stat.size < 2 || stat.size > this.limits.maxTextBytes + 8 * 1024)
+                throw new Error("Telegram admission record is not bounded");
+            const parsed = JSON.parse(fs.readFileSync(handle, "utf8"));
+            validateRecord(parsed, id);
+            this.assertRootIdentity();
+            return parsed;
+        }
+        finally {
+            fs.closeSync(handle);
+        }
+    }
+    list() {
+        this.assertRootIdentity();
+        const records = fs.readdirSync(this.root, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && /^[a-f0-9]{20}\.json$/u.test(entry.name))
+            .map((entry) => this.read(entry.name.slice(0, -5)));
+        this.assertRootIdentity();
+        return records;
+    }
+    write(record) {
+        this.assertRootIdentity();
+        validateRecord(record, record.id);
+        atomicWrite(this.filePath(record.id), record);
+        this.assertRootIdentity();
+    }
+    readSelfHealth() {
+        this.assertRootIdentity();
+        try {
+            const value = readBoundedPrivateJson(this.selfHealthPath(), 4 * 1024, "self-health");
+            if (value.schemaVersion !== 1 || value.code !== "telegram_admission_overflow" || !Number.isSafeInteger(value.count)
+                || value.count < 1 || !Number.isSafeInteger(value.lastObservedAt))
+                throw new Error("invalid");
+            this.assertRootIdentity();
+            return value;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            throw new Error("Telegram admission self-health is invalid", { cause: error });
+        }
+    }
+    recordOverflow() {
+        const now = this.now();
+        const current = this.readSelfHealth();
+        atomicWrite(this.selfHealthPath(), {
+            schemaVersion: 1,
+            code: "telegram_admission_overflow",
+            count: (current?.count ?? 0) + 1,
+            lastObservedAt: now,
+        });
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.telegram_admission_overflow",
+            message: "Telegram admission capacity was exceeded",
+            meta: { count: (current?.count ?? 0) + 1 },
+        });
+    }
+    capture(input, displayCode) {
+        return (0, session_transaction_1.withImmediateSessionTurnLease)(this.globalCoordinationPath(), () => this.captureExclusive(input, displayCode));
+    }
+    captureExclusive(input, displayCode) {
+        assertSafeInteger(input.updateId, "update id");
+        assertSafeInteger(input.messageId, "message id");
+        if (input.messageId < 1)
+            throw new Error("Telegram admission message id is invalid");
+        assertCanonicalId(input.botId, "bot id");
+        assertCanonicalId(input.userId, "user id");
+        assertCanonicalId(input.chatId, "chat id");
+        const now = this.now();
+        const records = this.compactTerminalRecords(this.list(), now);
+        if (this.recordRateAttempt(input, now)) {
+            this.recordOverflow();
+            return { kind: "overflow" };
+        }
+        const sameIdentity = records.filter((record) => identity(record) === identity(input))
+            .sort((left, right) => right.createdAt - left.createdAt);
+        const blocked = sameIdentity.find((record) => record.status === "blocked");
+        if (blocked)
+            return { kind: "blocked" };
+        const active = sameIdentity.find((record) => ACTIVE_STATUSES.has(record.status));
+        if (active)
+            return { kind: "existing", record: active };
+        const recentTerminal = sameIdentity[0];
+        if (recentTerminal && now - recentTerminal.updatedAt < this.limits.retryCooldownMs)
+            return { kind: "blocked" };
+        const textBytes = Buffer.byteLength(input.text, "utf8");
+        const pending = records.filter((record) => ACTIVE_STATUSES.has(record.status));
+        const pendingBytes = pending.reduce((total, record) => total + Buffer.byteLength(
+        /* v8 ignore next -- active records are validated to retain quarantined text; fallback is corruption defense @preserve */
+        record.quarantinedText ?? "", "utf8"), 0);
+        if (textBytes > this.limits.maxTextBytes || pending.length >= this.limits.maxPendingContacts
+            || pendingBytes + textBytes > this.limits.maxTotalBytes || this.limits.maxMessagesPerIdentity < 1) {
+            this.recordOverflow();
+            return { kind: "overflow" };
+        }
+        const id = admissionId(input);
+        const replay = records.find((record) => record.id === id);
+        /* v8 ignore next -- active same-identity records return above; an ID replay reaching here is necessarily terminal @preserve */
+        if (replay)
+            return ACTIVE_STATUSES.has(replay.status) ? { kind: "existing", record: replay } : { kind: "blocked" };
+        const record = {
+            schemaVersion: 1,
+            id,
+            revision: 0,
+            status: "pending",
+            botId: input.botId,
+            userId: input.userId,
+            chatId: input.chatId,
+            updateId: input.updateId,
+            messageId: input.messageId,
+            quarantinedText: input.text,
+            contentDigest: digest(input.text),
+            displayLabel: boundedLabel(input.displayLabel),
+            displayCode,
+            hasAttachments: input.hasAttachments,
+            createdAt: now,
+            updatedAt: now,
+            expiresAt: now + this.limits.retentionMs,
+            friendId: null,
+            acknowledgementArtifactId: null,
+            ownerCardArtifactId: null,
+            ingressSessionKey: null,
+            ingressEventId: null,
+            ingressReference: null,
+        };
+        this.write(record);
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.telegram_admission_captured",
+            message: "captured an unknown Telegram contact before friend resolution",
+            meta: { admissionId: id, hasAttachments: input.hasAttachments, textBytes },
+        });
+        return { kind: "created", record };
+    }
+    compareAndSwap(input) {
+        const current = this.read(input.admissionId);
+        if (current.status !== input.expectedStatus)
+            throw new Error(`Telegram admission CAS failed: expected ${input.expectedStatus}, found ${current.status}`);
+        const now = this.now();
+        const terminal = TERMINAL_STATUSES.has(input.nextStatus);
+        const updated = {
+            ...current,
+            status: input.nextStatus,
+            revision: current.revision + 1,
+            updatedAt: now,
+            ...(input.friendId ? { friendId: input.friendId } : {}),
+            ...(input.acknowledgementArtifactId ? { acknowledgementArtifactId: input.acknowledgementArtifactId } : {}),
+            ...(input.ownerCardArtifactId ? { ownerCardArtifactId: input.ownerCardArtifactId } : {}),
+            ...(input.ownerRelationship ? { ownerRelationship: input.ownerRelationship } : {}),
+            ...(input.ingress ? { ingressSessionKey: input.ingress.sessionKey, ingressEventId: input.ingress.eventId, ingressReference: input.ingress.reference } : {}),
+            ...(terminal || input.ingress ? { quarantinedText: null } : {}),
+        };
+        this.write(updated);
+        return updated;
+    }
+    recordEffect(admissionIdValue, kind, artifactId) {
+        const current = this.read(admissionIdValue);
+        if (current.status !== "pending")
+            return current;
+        const updated = {
+            ...current,
+            revision: current.revision + 1,
+            updatedAt: this.now(),
+            ...(kind === "acknowledgement" ? { acknowledgementArtifactId: artifactId } : { ownerCardArtifactId: artifactId }),
+        };
+        this.write(updated);
+        return updated;
+    }
+    releaseBlock(admissionIdValue) {
+        return (0, session_transaction_1.withImmediateSessionTurnLease)(this.globalCoordinationPath(), () => {
+            const current = this.read(admissionIdValue);
+            if (current.status !== "blocked")
+                throw new Error("Telegram admission is not blocked");
+            return this.compareAndSwap({ admissionId: current.id, expectedStatus: "blocked", nextStatus: "denied" });
+        });
+    }
+}
+exports.FileTelegramAdmissionStore = FileTelegramAdmissionStore;
+function ownerCard(record) {
+    return [
+        "Unknown Telegram contact",
+        `Unverified Telegram label: ${(0, telegram_client_1.escapeTelegramHtml)(record.displayLabel).replaceAll("'", "&#39;")}`,
+        `Verification code: ${(0, telegram_client_1.escapeTelegramHtml)(record.displayCode)}`,
+        "The message is quarantined and has not been processed.",
+        record.hasAttachments ? "Attachments were not downloaded and must be resent after approval." : null,
+    ].filter((line) => line !== null).join("\n");
+}
+function createTelegramAdmissionController(options) {
+    const now = options.now ?? Date.now;
+    const createDisplayCode = options.createDisplayCode ?? (() => crypto.randomBytes(4).toString("hex").toUpperCase());
+    const withDecisionLease = options.withDecisionLease ?? (async (_admissionId, work) => work());
+    const settleOwnerCard = async (record) => {
+        const text = record.status === "handled" ? "Allowed"
+            : record.status === "denied" ? "Denied"
+                : record.status === "blocked" ? "Blocked"
+                    : record.status === "expired" ? "Expired"
+                        : null;
+        if (!text || !record.ownerCardArtifactId)
+            return;
+        const messageId = options.resolveOwnerCardMessageId?.(record.ownerCardArtifactId);
+        if (!messageId)
+            return;
+        await options.sendEffect({
+            idempotencyKey: `owner-card-terminal:${record.id}:${record.status}`,
+            target: { kind: "approved_relationship", ...options.owner, requestId: record.id },
+            authorClass: "control",
+            effect: { kind: "edit", messageId, text },
+        });
+    };
+    const ensureEffects = async (initial) => {
+        let record = options.store.read(initial.id);
+        if (!record.acknowledgementArtifactId) {
+            const artifactIdValue = await options.sendEffect({
+                idempotencyKey: `ack:${record.id}`,
+                target: { kind: "admission_gate", admissionId: record.id, botId: record.botId, userId: record.userId, chatId: record.chatId },
+                authorClass: "control",
+                effect: { kind: "admission_ack", text: telegram_effect_adapter_1.FIXED_ADMISSION_ACKNOWLEDGEMENT },
+            });
+            record = options.store.recordEffect(record.id, "acknowledgement", artifactIdValue);
+        }
+        if (!record.ownerCardArtifactId) {
+            const artifactIdValue = await options.sendEffect({
+                idempotencyKey: `owner-card:${record.id}`,
+                target: { kind: "approved_relationship", ...options.owner, requestId: record.id },
+                authorClass: "control",
+                effect: { kind: "card", text: ownerCard(record), buttons: [[
+                            { text: "Allow", callbackData: `admit:${record.id}:allow` },
+                            { text: "Deny", callbackData: `admit:${record.id}:deny` },
+                            { text: "Block", callbackData: `admit:${record.id}:block` },
+                        ]] },
+            });
+            record = options.store.recordEffect(record.id, "owner_card", artifactIdValue);
+        }
+        return record;
+    };
+    const compensateFriend = async (record) => {
+        if (!record.friendId)
+            return;
+        await options.revokeCommunication?.({ userId: record.userId, chatId: record.chatId });
+        const revocation = await options.revokeFriend({
+            provider: "telegram-user",
+            botId: record.botId,
+            userId: record.userId,
+            chatId: record.chatId,
+            admissionId: record.id,
+            friendId: record.friendId,
+        });
+        if (revocation.kind === "collision")
+            throw new Error(`Telegram admission compensation collision: ${revocation.reason}`);
+    };
+    const resume = async (admissionIdValue) => {
+        let record = options.store.read(admissionIdValue);
+        if (record.status === "approved") {
+            const claim = await options.claimFriend({
+                provider: "telegram-user",
+                botId: record.botId,
+                userId: record.userId,
+                chatId: record.chatId,
+                admissionId: record.id,
+                displayLabel: record.displayLabel,
+                ...(record.ownerRelationship ? { relationship: record.ownerRelationship } : {}),
+                defaults: {
+                    trustLevel: "friend",
+                    admissionState: "active",
+                    initiativePolicy: "request_follow_up_only",
+                    capabilityProfileId: "sanctuary-household",
+                },
+            });
+            if (claim.kind === "collision") {
+                options.store.compareAndSwap({ admissionId: record.id, expectedStatus: "approved", nextStatus: "collision" });
+                (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.telegram_admission_collision", message: "Telegram admission Friend claim collided", meta: { admissionId: record.id } });
+                throw new Error(`Telegram admission collision: ${claim.reason}`);
+            }
+            record = options.store.compareAndSwap({ admissionId: record.id, expectedStatus: "approved", nextStatus: "friend_bound", friendId: claim.friendId });
+        }
+        try {
+            if (record.status === "friend_bound") {
+                await options.registerCommunication?.({
+                    id: record.id,
+                    updateId: record.updateId,
+                    userId: record.userId,
+                    chatId: record.chatId,
+                });
+                if (record.quarantinedText === null || !record.friendId)
+                    throw new Error("Telegram admission lost input before durable ingress");
+                const committedBase = await options.commitApprovedIngress({
+                    admissionId: record.id,
+                    idempotencyKey: `admission-turn:${record.id}`,
+                    friendId: record.friendId,
+                    botId: record.botId,
+                    userId: record.userId,
+                    chatId: record.chatId,
+                    updateId: record.updateId,
+                    messageId: record.messageId,
+                    text: record.quarantinedText,
+                    hasAttachments: record.hasAttachments,
+                    synthetic: false,
+                });
+                const committed = {
+                    ...committedBase,
+                    orientation: { ...exports.NEWLY_ADMITTED_ORIENTATION, attachmentsNeedResend: record.hasAttachments, ...(record.ownerRelationship ? { relationship: record.ownerRelationship } : {}) },
+                };
+                if (committed.admissionId !== record.id || committed.friendId !== record.friendId || committed.reference !== `telegram-admission:${record.id}`) {
+                    throw new Error("Telegram admission committed ingress changed identity");
+                }
+                await options.enqueueApprovedWork(committedBase);
+                record = options.store.compareAndSwap({ admissionId: record.id, expectedStatus: "friend_bound", nextStatus: "ingress_committed", ingress: committed });
+            }
+            if (record.status === "ingress_committed") {
+                record = options.store.compareAndSwap({ admissionId: record.id, expectedStatus: "ingress_committed", nextStatus: "turn_queued" });
+            }
+            if (!record.friendId || !record.ingressSessionKey || !record.ingressEventId || !record.ingressReference)
+                throw new Error("Telegram admission queued work lost its durable reference");
+            const settlement = await options.dispatchApprovedWork({
+                admissionId: record.id,
+                friendId: record.friendId,
+                sessionKey: record.ingressSessionKey,
+                eventId: record.ingressEventId,
+                reference: record.ingressReference,
+                orientation: { ...exports.NEWLY_ADMITTED_ORIENTATION, attachmentsNeedResend: record.hasAttachments, ...(record.ownerRelationship ? { relationship: record.ownerRelationship } : {}) },
+            });
+            if (settlement === "indeterminate") {
+                await compensateFriend(record);
+                return options.store.compareAndSwap({ admissionId: record.id, expectedStatus: "turn_queued", nextStatus: "indeterminate" });
+            }
+            record = options.store.compareAndSwap({ admissionId: record.id, expectedStatus: "turn_queued", nextStatus: "handled" });
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.telegram_admission_handled", message: "Telegram admission dispatched one approved user turn", meta: { admissionId: record.id, friendId: record.friendId } });
+        }
+        catch (error) {
+            const failed = options.store.read(record.id);
+            if (failed.friendId && !TERMINAL_STATUSES.has(failed.status)) {
+                await compensateFriend(failed);
+                options.store.compareAndSwap({ admissionId: failed.id, expectedStatus: failed.status, nextStatus: "indeterminate" });
+            }
+            throw error;
+        }
+        return record;
+    };
+    const reconcileExpired = async () => {
+        for (const candidate of options.store.list()) {
+            await withDecisionLease(candidate.id, async () => {
+                const record = options.store.read(candidate.id);
+                if (ACTIVE_STATUSES.has(record.status) && now() >= record.expiresAt) {
+                    await compensateFriend(record);
+                    const expired = options.store.compareAndSwap({ admissionId: record.id, expectedStatus: record.status, nextStatus: "expired" });
+                    await settleOwnerCard(expired);
+                    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.telegram_admission_expired", message: "Telegram admission expired and raw content was purged", meta: { admissionId: record.id } });
+                }
+            });
+        }
+    };
+    return {
+        async handleUnknown(input) {
+            const captured = options.store.capture(input, createDisplayCode());
+            if (!("record" in captured))
+                return { kind: captured.kind };
+            const record = await ensureEffects(captured.record);
+            return { kind: "pending", admissionId: record.id };
+        },
+        parseCallback(value, messageId) {
+            const match = /^admit:([a-f0-9]{20}):(allow|deny|block)$/u.exec(value);
+            if (!match)
+                throw new Error("Telegram admission callback is invalid");
+            const record = options.store.read(match[1]);
+            const binding = options.resolveOwnerCard(messageId);
+            if (!binding || binding.admissionId !== record.id || binding.artifactId !== record.ownerCardArtifactId)
+                throw new Error("Telegram admission callback is not bound to its owner card");
+            return { admissionId: match[1], decision: match[2] };
+        },
+        parseOwnerDecision(input) {
+            if (!input.replyToMessageId || Buffer.byteLength(input.text, "utf8") > 80)
+                return null;
+            const normalized = input.text.normalize("NFKC").trim().toLocaleLowerCase("en-US");
+            const kinshipMatch = /^yes,? (?:that(?:'|’)s|that is) my (brother|sister|sibling|mom|mother|mum|dad|father|parent|son|daughter|aunt|uncle|cousin|grandmother|grandma|grandfather|grandpa|wife|husband|partner)$/u.exec(normalized);
+            const relationship = kinshipMatch ? normalizeKinship(kinshipMatch[1]) : undefined;
+            const decision = /^(?:yes|allow|approve|let (?:them|him|her) in)$/u.test(normalized) || relationship ? "allow"
+                : /^(?:no|deny|decline)$/u.test(normalized) ? "deny"
+                    : /^(?:block|block (?:them|him|her))$/u.test(normalized) ? "block"
+                        : null;
+            if (!decision)
+                return null;
+            const binding = options.resolveOwnerCard(input.replyToMessageId);
+            if (!binding)
+                return null;
+            const record = options.store.read(binding.admissionId);
+            if (record.ownerCardArtifactId !== binding.artifactId || record.status !== "pending")
+                return null;
+            return { admissionId: record.id, decision, ...(relationship ? { relationship } : {}) };
+        },
+        async decide(input) {
+            return withDecisionLease(input.admissionId, async () => {
+                if (input.actorFriendId !== options.owner.friendId)
+                    throw new Error("Only the Telegram admission owner may decide");
+                let record = options.store.read(input.admissionId);
+                if (TERMINAL_STATUSES.has(record.status))
+                    return record;
+                if (record.status !== "pending")
+                    return resume(record.id);
+                if (now() >= record.expiresAt) {
+                    record = options.store.compareAndSwap({ admissionId: record.id, expectedStatus: "pending", nextStatus: "expired" });
+                    await settleOwnerCard(record);
+                    return record;
+                }
+                if (input.decision === "deny" || input.decision === "block") {
+                    record = options.store.compareAndSwap({ admissionId: record.id, expectedStatus: "pending", nextStatus: input.decision === "deny" ? "denied" : "blocked" });
+                    await settleOwnerCard(record);
+                    return record;
+                }
+                record = options.store.compareAndSwap({ admissionId: record.id, expectedStatus: "pending", nextStatus: "approved", ...(input.relationship ? { ownerRelationship: input.relationship } : {}) });
+                record = await resume(record.id);
+                await settleOwnerCard(record);
+                return record;
+            });
+        },
+        async reconcileExpired() { await reconcileExpired(); },
+        async recover() {
+            await reconcileExpired();
+            for (const record of options.store.list()) {
+                if (record.status === "pending")
+                    await ensureEffects(record);
+                else if (["approved", "friend_bound", "ingress_committed", "turn_queued"].includes(record.status)) {
+                    await withDecisionLease(record.id, async () => settleOwnerCard(await resume(record.id)));
+                }
+                else {
+                    await withDecisionLease(record.id, () => settleOwnerCard(record));
+                }
+            }
+        },
+    };
+}