@llblab/pi-telegram 0.46.0 → 0.47.0

package/dist/lib/workspace-retirement.js

@@ -0,0 +1,587 @@
+/**
+ * Workspace retirement preparation
+ * Zones: telegram, workspace identity, lifecycle
+ * Owns fail-closed protection composition, pressure selection, exact-intent admission,
+ * successor adoption, and gated mocked deletion with durable retirement commit.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { planTelegramWorkspaceSlotAllocation, } from "./workspace-slots.js";
+import { createTelegramWorkspaceAdmissionOperationId, isTelegramWorkspaceRetirementFence, runWithTelegramWorkspaceAdmissionsAsync, } from "./workspace-admission.js";
+export function createTelegramWorkspaceOperationGate() {
+    let tail = Promise.resolve();
+    return {
+        runExclusive(operation) {
+            const run = tail.then(operation);
+            tail = run.then(() => undefined, () => undefined);
+            return run;
+        },
+    };
+}
+export function createTelegramWorkspaceOperationRuntime(input = {}) {
+    const gate = createTelegramWorkspaceOperationGate();
+    const run = (metadata, operation) => {
+        const gated = () => gate.runExclusive(operation);
+        if (!input.getWorkspaceAdmission)
+            return gated();
+        const admission = input.getWorkspaceAdmission();
+        if (!admission) {
+            throw new Error("Telegram Workspace admission authority is unavailable.");
+        }
+        return runWithTelegramWorkspaceAdmissionsAsync({
+            ledger: admission,
+            ...metadata,
+            operation: gated,
+            onReleaseError(error) {
+                input.onReleaseError?.(error, metadata.operationKind);
+            },
+        });
+    };
+    return { run, runExclusive: gate.runExclusive };
+}
+export function captureTelegramWorkspaceJournalProtectionSources(input) {
+    const sources = [];
+    let complete = input.binding.journalBindingsComplete === true ||
+        input.discovery?.complete === true;
+    const capture = (scope, resolve) => {
+        try {
+            const binding = resolve();
+            if (!binding) {
+                complete = false;
+                sources.push({ kind: "unknown", scope });
+                return;
+            }
+            const snapshot = input.withJournalReference
+                ? input.withJournalReference(binding, binding.journal.read)
+                : binding.journal.read();
+            sources.push({ kind: "available", scope, entries: snapshot.entries });
+        }
+        catch {
+            complete = false;
+            sources.push({ kind: "unknown", scope });
+        }
+    };
+    capture({ kind: "shared" }, input.resolveLeader);
+    for (const journalBindingKey of input.binding.journalBindingKeys ?? []) {
+        capture({
+            kind: "binding",
+            bindingKey: input.binding.bindingKey,
+            journalBindingKey,
+        }, input.createFollowerResolver(journalBindingKey));
+    }
+    for (const path of input.discovery?.paths ?? []) {
+        capture({ kind: "discovered", path }, input.discovery.createResolver(path));
+    }
+    return { sources, complete };
+}
+function getJournalUpdateTarget(update) {
+    if (!update || typeof update !== "object" || Array.isArray(update))
+        return undefined;
+    const record = update;
+    if (record.message_reaction !== undefined)
+        return undefined;
+    const direct = record.message ?? record.edited_message ?? record.guest_message;
+    const callback = record.callback_query;
+    const message = direct ?? (callback && typeof callback === "object" && !Array.isArray(callback)
+        ? callback.message
+        : undefined);
+    if (!message || typeof message !== "object" || Array.isArray(message))
+        return undefined;
+    const messageRecord = message;
+    const chat = messageRecord.chat;
+    if (!chat || typeof chat !== "object" || Array.isArray(chat))
+        return undefined;
+    const chatId = chat.id;
+    if (typeof chatId !== "number")
+        return undefined;
+    const threadId = messageRecord.message_thread_id;
+    return {
+        chatId,
+        ...(typeof threadId === "number" ? { threadId } : {}),
+    };
+}
+function sameTarget(left, right) {
+    return left.chatId === right.chatId && left.threadId === right.threadId;
+}
+export function resolveTelegramWorkspaceAcceptedWorkProtection(input) {
+    if (input.localAcceptedTargets.some((target) => sameTarget(target, input.binding.target))) {
+        return "protected";
+    }
+    let unknown = !input.sourcesComplete;
+    for (const source of input.journalSources) {
+        const relevant = source.scope.kind !== "binding" ||
+            source.scope.bindingKey === input.binding.bindingKey;
+        if (!relevant)
+            continue;
+        if (source.kind === "unknown") {
+            unknown = true;
+            continue;
+        }
+        if (source.scope.kind === "binding" && source.entries.length > 0) {
+            return "protected";
+        }
+        for (const entry of source.entries) {
+            const target = getJournalUpdateTarget(entry.update);
+            if (!target) {
+                unknown = true;
+                continue;
+            }
+            if (sameTarget(target, input.binding.target))
+                return "protected";
+        }
+    }
+    return unknown ? "unknown" : "clear";
+}
+export async function pruneTelegramWorkspaceJournalEvidence(input) {
+    const operation = async () => {
+        const leaderEpoch = input.getLeaderEpoch();
+        const profileKey = input.getProfileKey();
+        const isCurrent = () => leaderEpoch !== undefined &&
+            input.getLeaderEpoch() === leaderEpoch &&
+            input.getProfileKey() === profileKey &&
+            input.isCurrent?.() !== false;
+        if (!isCurrent()) {
+            throw new Error("Telegram Workspace journal pruning requires current leader authority.");
+        }
+        const shared = input.capture.sources.filter((source) => source.scope.kind === "shared");
+        const bindingSources = input.capture.sources.filter((source) => source.scope.kind === "binding" &&
+            source.scope.bindingKey === input.binding.bindingKey);
+        const sourceByKey = new Map(bindingSources.flatMap((source) => source.scope.kind === "binding"
+            ? [[source.scope.journalBindingKey, source]]
+            : []));
+        if (!input.capture.complete ||
+            shared.length !== 1 ||
+            shared[0]?.kind !== "available" ||
+            bindingSources.length !==
+                (input.binding.journalBindingKeys ?? []).length ||
+            sourceByKey.size !== (input.binding.journalBindingKeys ?? []).length ||
+            Array.from(sourceByKey.values()).some((source) => source.kind !== "available")) {
+            return { kind: "blocked", reason: "incomplete-evidence" };
+        }
+        const emptyKeys = (input.binding.journalBindingKeys ?? []).filter((key) => {
+            const source = sourceByKey.get(key);
+            return source?.kind === "available" && source.entries.length === 0;
+        });
+        if (emptyKeys.some((key) => input.getJournalWriterProtection(key) !== "clear")) {
+            return { kind: "blocked", reason: "writer-not-quiescent" };
+        }
+        const retainedKeys = (input.binding.journalBindingKeys ?? []).filter((key) => !emptyKeys.includes(key));
+        if (!isCurrent()) {
+            throw new Error("Telegram Workspace journal pruning lost leader authority.");
+        }
+        const binding = input.store.commitWorkspaceJournalEvidence(input.binding, retainedKeys, input.binding.journalBindingsComplete === true);
+        if (!binding)
+            return { kind: "blocked", reason: "state-changed" };
+        const removedKeys = (input.binding.journalBindingKeys ?? []).filter((key) => !retainedKeys.includes(key));
+        if (removedKeys.length > 0)
+            await input.store.persist();
+        if (!isCurrent()) {
+            throw new Error("Telegram Workspace journal pruning lost leader authority.");
+        }
+        return { kind: "committed", binding, removedKeys };
+    };
+    return runWithTelegramWorkspaceAdmissionsAsync({
+        ledger: input.admission,
+        operationId: createTelegramWorkspaceAdmissionOperationId(),
+        operationKind: "workspace.prune-journal-evidence",
+        scopes: [{ kind: "target", target: input.binding.target }],
+        operation,
+        onReleaseError(error) {
+            input.onAdmissionReleaseError?.(error);
+        },
+    });
+}
+export function captureTelegramWorkspaceExternalProtection(input) {
+    let liveOwner = "unknown";
+    let acceptedWork = "unknown";
+    let deliveryAuthority = "unknown";
+    try {
+        liveOwner = input.getLiveOwnerProtection(input.binding);
+    }
+    catch {
+        // Unavailable registry/process evidence must not clear a binding.
+    }
+    try {
+        const journals = input.captureJournalSources(input.binding);
+        const local = input.getLocalAcceptedTargets(input.binding);
+        acceptedWork = resolveTelegramWorkspaceAcceptedWorkProtection({
+            binding: input.binding,
+            localAcceptedTargets: local.targets,
+            journalSources: journals.sources,
+            sourcesComplete: journals.complete && local.complete,
+        });
+    }
+    catch {
+        // Unavailable queue or journal evidence must not clear accepted work.
+    }
+    try {
+        deliveryAuthority = input.getDeliveryAuthorityProtection?.(input.binding) ?? "unknown";
+    }
+    catch {
+        // Unavailable delivery evidence must not clear a binding.
+    }
+    return { liveOwner, acceptedWork, deliveryAuthority };
+}
+export function createTelegramWorkspaceExternalProtectionCapture(deps) {
+    return function (binding) {
+        return captureTelegramWorkspaceExternalProtection({
+            binding,
+            getLiveOwnerProtection(candidate) {
+                if (deps.listFollowers().some((follower) => !!follower.target && sameTarget(follower.target, candidate.target)))
+                    return "protected";
+                if (!deps.getJournalWriterProtection)
+                    return "unknown";
+                let unknown = candidate.journalBindingsComplete !== true;
+                for (const journalBindingKey of candidate.journalBindingKeys ?? []) {
+                    const protection = deps.getJournalWriterProtection(journalBindingKey);
+                    if (protection === "protected")
+                        return "protected";
+                    if (protection === "unknown")
+                        unknown = true;
+                }
+                return unknown ? "unknown" : "clear";
+            },
+            getLocalAcceptedTargets(candidate) {
+                const items = deps.getQueuedItems();
+                const targets = [];
+                const activeTarget = deps.getActiveTurnTarget();
+                if (activeTarget)
+                    targets.push(activeTarget);
+                let complete = true;
+                for (const item of items) {
+                    if (item.target)
+                        targets.push(item.target);
+                    else if (item.chatId === candidate.target.chatId)
+                        complete = false;
+                }
+                return { targets, complete };
+            },
+            captureJournalSources(candidate) {
+                const discovery = candidate.journalBindingsComplete === true
+                    ? undefined
+                    : deps.discoverFollowerJournals?.();
+                return captureTelegramWorkspaceJournalProtectionSources({
+                    binding: candidate,
+                    resolveLeader: deps.resolveLeaderJournal,
+                    createFollowerResolver: deps.createFollowerJournalResolver,
+                    ...(deps.withJournalReference
+                        ? { withJournalReference: deps.withJournalReference } : {}),
+                    ...(discovery && deps.createJournalPathResolver
+                        ? { discovery: {
+                                ...discovery,
+                                createResolver: deps.createJournalPathResolver,
+                            } }
+                        : {}),
+                });
+            },
+            ...(deps.getDeliveryAuthorityProtection
+                ? { getDeliveryAuthorityProtection: deps.getDeliveryAuthorityProtection }
+                : {}),
+        });
+    };
+}
+export async function adoptTelegramWorkspaceRetirementIntent(input) {
+    return input.runExclusive(async () => {
+        const leaderEpoch = input.getLeaderEpoch();
+        const profileKey = input.getProfileKey();
+        const isCurrent = () => leaderEpoch !== undefined && input.getLeaderEpoch() === leaderEpoch &&
+            input.getProfileKey() === profileKey && input.isCurrent?.() !== false;
+        if (!isCurrent())
+            throw new Error("Telegram Workspace retirement adoption requires current leader authority.");
+        const intents = input.store.listWorkspaceRetirementIntents();
+        if (intents.length !== 1 || !isDeepStrictEqual(intents[0], input.intent)) {
+            return { kind: "blocked", reason: "intent-conflict" };
+        }
+        if (input.intent.profileKey !== profileKey) {
+            return { kind: "blocked", reason: "profile-changed" };
+        }
+        const binding = input.store.listWorkspaceBindings().find((candidate) => candidate.bindingKey === input.intent.binding.bindingKey);
+        if (!binding || !isDeepStrictEqual(binding, input.intent.binding)) {
+            return { kind: "blocked", reason: "binding-changed" };
+        }
+        const eligible = input.store.captureWorkspaceSlotOccupancy(input.getExternalProtection, { expectedRetirement: input.intent }).bindings.find((candidate) => candidate.bindingKey === binding.bindingKey)?.protection === "eligible";
+        if (!eligible)
+            return { kind: "blocked", reason: "protection-changed" };
+        const replacement = { ...input.intent, leaderEpoch: leaderEpoch };
+        if (!isCurrent())
+            throw new Error("Telegram Workspace retirement adoption lost leader authority.");
+        if (!await input.store.replaceWorkspaceRetirementIntent(input.intent, replacement, isCurrent))
+            return { kind: "blocked", reason: "commit-rejected" };
+        return { kind: "adopted", intent: replacement };
+    });
+}
+function isTelegramWorkspaceDeletionConfirmedAbsent(error) {
+    if (!(error instanceof Error))
+        return false;
+    const status = "status" in error && typeof error.status === "number"
+        ? error.status : undefined;
+    if (status !== undefined && status !== 400)
+        return false;
+    const message = error.message.toLowerCase();
+    return message.includes("topic_id_invalid") ||
+        message.includes("message thread not found") ||
+        message.includes("thread not found") ||
+        message.includes("topic not found") ||
+        message.includes("topic deleted");
+}
+function matchesTelegramWorkspaceRetirementFence(fence, intent) {
+    return (fence.retirementIntentId === intent.id &&
+        fence.profileKey === intent.profileKey &&
+        fence.bindingKey === intent.binding.bindingKey &&
+        fence.slot === intent.binding.slot &&
+        fence.target.chatId === intent.binding.target.chatId &&
+        fence.target.threadId === intent.binding.target.threadId &&
+        fence.retirementRequestedAtMs === intent.requestedAtMs);
+}
+export async function executeTelegramWorkspaceRetirement(input) {
+    return input.runExclusive(async () => {
+        const isCurrent = () => input.getLeaderEpoch() === input.intent.leaderEpoch &&
+            input.getProfileKey() === input.intent.profileKey &&
+            input.isCurrent?.() !== false;
+        if (!isCurrent())
+            return { kind: "retained", reason: "authority-changed" };
+        if (!input.intent.binding.slot || !/^[A-Z]$/u.test(input.intent.binding.slot)) {
+            return { kind: "retained", reason: "stale-intent" };
+        }
+        const owner = input.admission.getOwner();
+        const storedFence = input.admission.read().fence;
+        if (storedFence && !isTelegramWorkspaceRetirementFence(storedFence)) {
+            return { kind: "retained", reason: "fence-conflict" };
+        }
+        let fence = storedFence;
+        if (fence && !matchesTelegramWorkspaceRetirementFence(fence, input.intent)) {
+            return { kind: "retained", reason: "fence-conflict" };
+        }
+        if (fence &&
+            (fence.leaderEpoch !== input.intent.leaderEpoch ||
+                fence.owner.processId !== owner.processId ||
+                fence.owner.processBirthId !== owner.processBirthId)) {
+            fence = input.admission.adoptRetirementFence(fence, {
+                owner,
+                leaderEpoch: input.intent.leaderEpoch,
+            });
+        }
+        const intent = input.store.listWorkspaceRetirementIntents().find((candidate) => isDeepStrictEqual(candidate, input.intent));
+        const binding = input.store.listWorkspaceBindings().find((candidate) => candidate.bindingKey === input.intent.binding.bindingKey);
+        if (!intent || !binding || !isDeepStrictEqual(binding, input.intent.binding)) {
+            if (!intent && !binding && fence?.phase === "commit-ready") {
+                try {
+                    input.admission.completeRetirementFence(fence);
+                }
+                catch {
+                    if (input.admission.read().fence) {
+                        return { kind: "retained", reason: "fence-release-unconfirmed" };
+                    }
+                }
+                return {
+                    kind: "retired",
+                    bindingKey: input.intent.binding.bindingKey,
+                    slot: input.intent.binding.slot,
+                };
+            }
+            return { kind: "retained", reason: "stale-intent" };
+        }
+        const eligible = () => input.store.captureWorkspaceSlotOccupancy(input.getExternalProtection, { expectedRetirement: input.intent }).bindings.find((candidate) => candidate.bindingKey === input.intent.binding.bindingKey)?.protection === "eligible";
+        if (!eligible())
+            return { kind: "retained", reason: "protection-changed" };
+        if (!fence) {
+            const acquired = input.admission.acquireRetirementFence({
+                operationId: `workspace-retirement:${input.intent.id}`,
+                retirementIntentId: input.intent.id,
+                bindingKey: binding.bindingKey,
+                slot: binding.slot,
+                target: binding.target,
+                leaderEpoch: input.intent.leaderEpoch,
+                retirementRequestedAtMs: input.intent.requestedAtMs,
+            });
+            if (acquired.kind === "blocked") {
+                return {
+                    kind: "retained",
+                    reason: acquired.reason === "admission-active"
+                        ? "admission-active"
+                        : "fence-conflict",
+                };
+            }
+            fence = acquired.fence;
+        }
+        if (!isCurrent())
+            return { kind: "retained", reason: "authority-changed" };
+        if (fence.phase === "fenced" && !eligible()) {
+            input.admission.releaseUnissuedRetirementFence(fence);
+            return { kind: "retained", reason: "protection-changed" };
+        }
+        if (fence.phase === "fenced") {
+            const issued = input.admission.issueDeletionPermit(fence);
+            if (issued.kind !== "issued") {
+                return { kind: "retained", reason: "delete-unconfirmed" };
+            }
+            fence = issued.fence;
+            try {
+                await input.deleteForumTopic(issued.permit, {
+                    chat_id: binding.target.chatId,
+                    message_thread_id: binding.target.threadId,
+                }, { maxAttempts: 1 });
+            }
+            catch (error) {
+                if (!isTelegramWorkspaceDeletionConfirmedAbsent(error)) {
+                    return { kind: "retained", reason: "delete-unconfirmed" };
+                }
+            }
+            fence = input.admission.confirmRetirementAbsence(fence);
+        }
+        else if (fence.phase === "deletion-issued") {
+            const absence = await input.confirmTargetAbsent?.(binding.target);
+            if (absence !== "absent") {
+                return { kind: "retained", reason: "delete-unconfirmed" };
+            }
+            fence = input.admission.confirmRetirementAbsence(fence);
+        }
+        if (!isCurrent())
+            return { kind: "retained", reason: "authority-changed" };
+        if (!eligible())
+            return { kind: "retained", reason: "protection-changed" };
+        if (!await input.store.commitWorkspaceRetirement(input.intent, isCurrent)) {
+            return { kind: "retained", reason: "commit-rejected" };
+        }
+        try {
+            input.admission.completeRetirementFence(fence);
+        }
+        catch {
+            if (input.admission.read().fence) {
+                return { kind: "retained", reason: "fence-release-unconfirmed" };
+            }
+        }
+        return {
+            kind: "retired",
+            bindingKey: binding.bindingKey,
+            slot: binding.slot,
+        };
+    });
+}
+function findEligibleCandidate(occupancy, reservedSlots, nowMs) {
+    const allocation = planTelegramWorkspaceSlotAllocation({
+        bindings: occupancy,
+        reservedSlots,
+        nowMs,
+    });
+    if (allocation.kind === "free") {
+        return { kind: "not-needed", reason: "free-capacity" };
+    }
+    if (allocation.kind === "blocked")
+        return allocation;
+    return { kind: "candidate", candidate: allocation.candidate };
+}
+export async function prepareTelegramWorkspaceRetirement(deps) {
+    const getNowMs = deps.getNowMs ?? Date.now;
+    const leaderEpoch = deps.getLeaderEpoch();
+    const profileKey = deps.getProfileKey();
+    const isCurrent = () => leaderEpoch !== undefined &&
+        deps.getLeaderEpoch() === leaderEpoch &&
+        deps.getProfileKey() === profileKey &&
+        deps.isCurrent?.() !== false;
+    if (!isCurrent())
+        throw new Error("Telegram Workspace retirement requires current leader authority.");
+    const existing = deps.store.listWorkspaceRetirementIntents();
+    if (existing.length > 1) {
+        return { kind: "blocked", reason: "existing-intent-conflict" };
+    }
+    if (existing.length === 1) {
+        const intent = existing[0];
+        const binding = deps.store.listWorkspaceBindings().find((candidate) => candidate.bindingKey === intent.binding.bindingKey);
+        const snapshot = deps.store.captureWorkspaceSlotOccupancy(deps.getExternalProtection, { expectedRetirement: intent });
+        const candidate = snapshot.bindings.find((entry) => entry.bindingKey === intent.binding.bindingKey);
+        if (intent.profileKey !== profileKey ||
+            intent.leaderEpoch !== leaderEpoch ||
+            !binding || !isDeepStrictEqual(binding, intent.binding) ||
+            candidate?.protection !== "eligible") {
+            return { kind: "blocked", reason: "stale-intent" };
+        }
+        if (!isCurrent())
+            throw new Error("Telegram Workspace retirement lost leader authority.");
+        await deps.store.persist();
+        if (!isCurrent())
+            throw new Error("Telegram Workspace retirement lost leader authority.");
+        return { kind: "ready", intent };
+    }
+    const nowMs = getNowMs();
+    const snapshot = deps.store.captureWorkspaceSlotOccupancy(deps.getExternalProtection);
+    const selection = findEligibleCandidate(snapshot.bindings, snapshot.reservedSlots, nowMs);
+    if (selection.kind !== "candidate")
+        return selection;
+    const selected = selection.candidate;
+    const binding = deps.store.listWorkspaceBindings().find((candidate) => candidate.bindingKey === selected.bindingKey);
+    if (!binding?.slot ||
+        binding.slot.toLowerCase() !== selected.slot ||
+        binding.inactiveSinceMs !== selected.inactiveSinceMs) {
+        return { kind: "blocked", reason: "state-changed" };
+    }
+    const intent = {
+        id: `workspace-retirement:pressure:${binding.bindingKey}:${binding.slot}:${binding.inactiveSinceMs}`,
+        reason: "pressure",
+        profileKey,
+        binding,
+        leaderEpoch: leaderEpoch,
+        requestedAtMs: nowMs,
+    };
+    if (!isCurrent())
+        throw new Error("Telegram Workspace retirement lost leader authority.");
+    if (!deps.store.upsertWorkspaceRetirementIntent(intent)) {
+        return { kind: "blocked", reason: "state-changed" };
+    }
+    const rechecked = deps.store.captureWorkspaceSlotOccupancy(deps.getExternalProtection, { expectedRetirement: intent }).bindings.find((candidate) => candidate.bindingKey === binding.bindingKey);
+    if (rechecked?.protection !== "eligible" || !isCurrent()) {
+        deps.store.removeWorkspaceRetirementIntent(intent);
+        if (!isCurrent())
+            throw new Error("Telegram Workspace retirement lost leader authority.");
+        return { kind: "blocked", reason: "state-changed" };
+    }
+    await deps.store.persist();
+    if (!isCurrent())
+        throw new Error("Telegram Workspace retirement lost leader authority.");
+    return { kind: "ready", intent };
+}
+export async function runTelegramWorkspaceRetirementLifecycle(input) {
+    let intent = input.store.listWorkspaceRetirementIntents()[0];
+    if (intent) {
+        const adoption = await adoptTelegramWorkspaceRetirementIntent({
+            store: input.store,
+            intent,
+            getExternalProtection: input.getExternalProtection,
+            getLeaderEpoch: input.getLeaderEpoch,
+            getProfileKey: input.getProfileKey,
+            isCurrent: input.isCurrent,
+            runExclusive: input.runExclusive,
+        });
+        if (adoption.kind !== "adopted") {
+            return { kind: "blocked", stage: "adoption", reason: adoption.reason };
+        }
+        intent = adoption.intent;
+    }
+    else {
+        const preparation = await prepareTelegramWorkspaceRetirement({
+            store: input.store,
+            getExternalProtection: input.getExternalProtection,
+            getLeaderEpoch: input.getLeaderEpoch,
+            getProfileKey: input.getProfileKey,
+            isCurrent: input.isCurrent,
+            getNowMs: input.getNowMs,
+        });
+        if (preparation.kind === "not-needed")
+            return preparation;
+        if (preparation.kind === "blocked") {
+            return { kind: "blocked", stage: "preparation", reason: preparation.reason };
+        }
+        intent = preparation.intent;
+    }
+    return executeTelegramWorkspaceRetirement({
+        store: input.store,
+        intent,
+        getExternalProtection: input.getExternalProtection,
+        getLeaderEpoch: input.getLeaderEpoch,
+        getProfileKey: input.getProfileKey,
+        isCurrent: input.isCurrent,
+        runExclusive: input.runExclusive,
+        admission: input.admission,
+        deleteForumTopic: input.deleteForumTopic,
+        confirmTargetAbsent: input.confirmTargetAbsent,
+    });
+}

package/dist/lib/workspace-slots.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Workspace slot allocation policy
+ * Zones: telegram, workspace identity
+ * Owns bounded profile-wide letter selection and inactivity ordering.
+ * Excludes liveness discovery, persistence, routing, and Telegram deletion;
+ * a selection is a proposal, never authority to retire a binding.
+ */
+export declare const TELEGRAM_WORKSPACE_SLOTS = "abcdefghijklmnopqrstuvwxyz";
+export interface TelegramWorkspaceSlotOccupancy {
+    bindingKey: string;
+    slot: string;
+    inactiveSinceMs?: number;
+    protection: "eligible" | "protected" | "unknown";
+}
+export type TelegramWorkspaceSlotAllocation = {
+    kind: "free";
+    slot: string;
+} | {
+    kind: "reclaim";
+    candidate: TelegramWorkspaceSlotOccupancy;
+} | {
+    kind: "blocked";
+    reason: "invalid-state" | "protected-capacity";
+};
+/** Caller must recheck exact ownership and protected work before retirement. */
+export declare function planTelegramWorkspaceSlotAllocation(input: {
+    bindings: readonly TelegramWorkspaceSlotOccupancy[];
+    reservedSlots: readonly string[];
+    nowMs: number;
+}): TelegramWorkspaceSlotAllocation;

package/dist/lib/workspace-slots.js

@@ -0,0 +1,54 @@
+/**
+ * Workspace slot allocation policy
+ * Zones: telegram, workspace identity
+ * Owns bounded profile-wide letter selection and inactivity ordering.
+ * Excludes liveness discovery, persistence, routing, and Telegram deletion;
+ * a selection is a proposal, never authority to retire a binding.
+ */
+export const TELEGRAM_WORKSPACE_SLOTS = "abcdefghijklmnopqrstuvwxyz";
+function isSlot(slot) {
+    return /^[a-z]$/u.test(slot);
+}
+function isValidSnapshot(bindings, reservedSlots, nowMs) {
+    if (!Number.isFinite(nowMs) || nowMs < 0)
+        return false;
+    const slots = new Set();
+    const keys = new Set();
+    for (const binding of bindings) {
+        if (!isSlot(binding.slot) || !binding.bindingKey ||
+            slots.has(binding.slot) || keys.has(binding.bindingKey))
+            return false;
+        slots.add(binding.slot);
+        keys.add(binding.bindingKey);
+    }
+    return reservedSlots.every(isSlot);
+}
+function eligibleByInactivity(bindings, reservedSlots, nowMs) {
+    const reserved = new Set(reservedSlots);
+    return bindings.filter((binding) => binding.protection === "eligible" &&
+        !reserved.has(binding.slot) &&
+        typeof binding.inactiveSinceMs === "number" &&
+        Number.isFinite(binding.inactiveSinceMs) &&
+        binding.inactiveSinceMs >= 0 &&
+        binding.inactiveSinceMs <= nowMs).sort((left, right) => left.inactiveSinceMs - right.inactiveSinceMs ||
+        left.slot.charCodeAt(0) - right.slot.charCodeAt(0));
+}
+/** Caller must recheck exact ownership and protected work before retirement. */
+export function planTelegramWorkspaceSlotAllocation(input) {
+    const { bindings, reservedSlots, nowMs } = input;
+    if (!isValidSnapshot(bindings, reservedSlots, nowMs)) {
+        return { kind: "blocked", reason: "invalid-state" };
+    }
+    const occupied = new Set([
+        ...bindings.map((binding) => binding.slot),
+        ...reservedSlots,
+    ]);
+    for (const slot of TELEGRAM_WORKSPACE_SLOTS) {
+        if (!occupied.has(slot))
+            return { kind: "free", slot };
+    }
+    const candidate = eligibleByInactivity(bindings, reservedSlots, nowMs)[0];
+    return candidate
+        ? { kind: "reclaim", candidate: { ...candidate } }
+        : { kind: "blocked", reason: "protected-capacity" };
+}