@llblab/pi-kit 0.27.6 → 0.28.0

package/node_modules/@llblab/pi-telegram/dist/lib/wire.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Non-coercing decoded wire-value inspection
+ * Zones: wire fields, record shape, integer bounds
+ * Owns shared shallow predicates; excludes schemas, lossless decoding,
+ * required fields, normalization, storage and execution authority.
+ */
+/** Non-array object shape only; not a plain-object or JSON-serializability guarantee. */
+export declare function isWireRecord(value: unknown): value is Record<string, unknown>;
+/** Checks only own enumerable string keys, not required, inherited or symbol fields. */
+export declare function hasOnlyWireKeys(value: Record<string, unknown>, allowedKeys: readonly string[]): boolean;
+export declare function isNonEmptyWireString(value: unknown): value is string;
+export declare function isNonNegativeWireInteger(value: unknown): value is number;

package/node_modules/@llblab/pi-telegram/dist/lib/wire.js

@@ -0,0 +1,21 @@
+/**
+ * Non-coercing decoded wire-value inspection
+ * Zones: wire fields, record shape, integer bounds
+ * Owns shared shallow predicates; excludes schemas, lossless decoding,
+ * required fields, normalization, storage and execution authority.
+ */
+/** Non-array object shape only; not a plain-object or JSON-serializability guarantee. */
+export function isWireRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/** Checks only own enumerable string keys, not required, inherited or symbol fields. */
+export function hasOnlyWireKeys(value, allowedKeys) {
+    const allowed = new Set(allowedKeys);
+    return Object.keys(value).every(key => allowed.has(key));
+}
+export function isNonEmptyWireString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+export function isNonNegativeWireInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}

package/node_modules/@llblab/pi-telegram/dist/lib/workspace-admission.d.ts

@@ -6,7 +6,7 @@
  */
 import { type PathLike } from "node:fs";
 import { type TelegramProcessLiveness } from "./bus.ts";
-import type { TelegramTarget } from "./target.ts";
+import { type TelegramTarget } from "./target.ts";
 export interface TelegramWorkspaceAdmissionOwner {
     processId: number;
     processBirthId: string;
@@ -22,7 +22,7 @@ export type TelegramWorkspaceAdmissionScope = {
 } | {
     kind: "profile";
 };
-export interface TelegramWorkspaceAdmissionLease {
+interface TelegramWorkspaceAdmissionLease {
     operationId: string;
     operationKind: string;
     profileKey: string;
@@ -30,9 +30,9 @@ export interface TelegramWorkspaceAdmissionLease {
     owner: TelegramWorkspaceAdmissionOwner;
     acquiredAtMs: number;
 }
-export type TelegramWorkspaceDestructiveFenceKind = "pressure-retirement" | "manual-thread-cleanup" | "journal-writer-closure";
+type TelegramWorkspaceDestructiveFenceKind = "pressure-retirement" | "manual-thread-cleanup" | "journal-writer-closure";
 export type TelegramWorkspaceDeletionFenceKind = Exclude<TelegramWorkspaceDestructiveFenceKind, "journal-writer-closure">;
-export interface TelegramWorkspaceJournalWriterClosureFence {
+interface TelegramWorkspaceJournalWriterClosureFence {
     destructiveKind: "journal-writer-closure";
     phase: "fenced";
     operationId: string;
@@ -43,7 +43,7 @@ export interface TelegramWorkspaceJournalWriterClosureFence {
     acquiredAtMs: number;
 }
 export declare function normalizeTelegramWorkspaceJournalWriterClosureFence(value: unknown, profileKey: string): TelegramWorkspaceJournalWriterClosureFence | undefined;
-export interface TelegramWorkspaceJournalWriterProtocolMode {
+interface TelegramWorkspaceJournalWriterProtocolMode {
     version: 1;
     protocol: "custody-v3";
     profileKey: string;
@@ -100,8 +100,7 @@ export interface TelegramWorkspaceDeletionPermit {
     readonly leaderEpoch: number | string;
     readonly issuedAtMs: number;
 }
-export type TelegramWorkspaceAdmissionBlockReason = "retirement-fenced" | "admission-active" | "retirement-active";
-export type TelegramWorkspaceAdmissionAcquireResult = {
+type TelegramWorkspaceAdmissionAcquireResult = {
     kind: "acquired";
     lease: TelegramWorkspaceAdmissionLease;
     resumed: boolean;
@@ -109,7 +108,7 @@ export type TelegramWorkspaceAdmissionAcquireResult = {
     kind: "blocked";
     reason: "retirement-fenced";
 };
-export type TelegramWorkspaceRetirementFenceAcquireResult = {
+type TelegramWorkspaceRetirementFenceAcquireResult = {
     kind: "acquired";
     fence: TelegramWorkspaceRetirementFence;
     resumed: boolean;
@@ -117,11 +116,11 @@ export type TelegramWorkspaceRetirementFenceAcquireResult = {
     kind: "blocked";
     reason: "admission-active" | "retirement-active";
 };
-export type TelegramWorkspaceJournalWriterProtocolInstallResult = {
+type TelegramWorkspaceJournalWriterProtocolInstallResult = {
     mode: TelegramWorkspaceJournalWriterProtocolMode;
     resumed: boolean;
 };
-export type TelegramWorkspaceJournalWriterClosureAcquireResult = {
+type TelegramWorkspaceJournalWriterClosureAcquireResult = {
     kind: "acquired";
     fence: TelegramWorkspaceJournalWriterClosureFence;
     resumed: boolean;
@@ -129,7 +128,7 @@ export type TelegramWorkspaceJournalWriterClosureAcquireResult = {
     kind: "blocked";
     reason: "admission-active" | "retirement-active";
 };
-export type TelegramWorkspaceDeletionPermitResult = {
+type TelegramWorkspaceDeletionPermitResult = {
     kind: "issued";
     fence: TelegramWorkspaceRetirementFence;
     permit: TelegramWorkspaceDeletionPermit;
@@ -137,15 +136,17 @@ export type TelegramWorkspaceDeletionPermitResult = {
     kind: "already-issued";
     fence: TelegramWorkspaceRetirementFence;
 };
-export interface TelegramWorkspaceAdmissionLedgerSnapshot {
+interface TelegramWorkspaceAdmissionLedgerSnapshot {
     profileKey: string;
     leases: TelegramWorkspaceAdmissionLease[];
     fence?: TelegramWorkspaceDestructiveFence;
     writerProtocolMode?: TelegramWorkspaceJournalWriterProtocolMode;
 }
-export type TelegramWorkspaceAdmissionPublicationBoundary = "before-write" | "after-write-before-rename";
-export interface TelegramWorkspaceAdmissionLedgerOptions {
+type TelegramWorkspaceAdmissionPublicationBoundary = "before-write" | "after-write-before-rename";
+interface TelegramWorkspaceAdmissionLedgerOptions {
     path: string;
+    /** Explicit logical section identity for the consolidated root; absent means the standalone ledger adapter. */
+    stateProfile?: string;
     profileKey: string;
     owner: TelegramWorkspaceAdmissionOwner;
     getNowMs?: () => number;
@@ -232,22 +233,29 @@ export interface TelegramWorkspaceAdmissionLedger {
 export declare function resolveTelegramWorkspaceDestructiveFenceKind(fence: {
     destructiveKind?: TelegramWorkspaceDestructiveFenceKind;
 }): TelegramWorkspaceDestructiveFenceKind;
+/** Pure damage check for one consolidated admission section under its own stored profile key; throws when invalid. */
+export declare function assertTelegramConsolidatedAdmissionSection(value: unknown, stateProfile: string): void;
 export declare function createTelegramWorkspaceAdmissionOperationId(): string;
 export declare function createTelegramWorkspaceAdmissionProfileKey(input: {
     profileName?: string;
     botToken: string;
 }): string;
-export interface TelegramWorkspaceAdmissionRuntimeBinding {
+interface TelegramWorkspaceAdmissionRuntimeBinding {
     resolve: () => TelegramWorkspaceAdmissionLedger | undefined;
 }
 export declare function createTelegramWorkspaceAdmissionRuntimeBinding(input: {
     getProfileName: () => string | undefined;
     getBotToken: () => string | undefined;
-    getPath: (profileName?: string) => string;
     owner: TelegramWorkspaceAdmissionOwner;
     getNowMs?: () => number;
     getProcessLiveness?: (owner: TelegramWorkspaceAdmissionOwner) => TelegramProcessLiveness;
-}): TelegramWorkspaceAdmissionRuntimeBinding;
+} & ({
+    getPath: (profileName?: string) => string;
+    getStatePath?: never;
+} | {
+    getStatePath: () => string;
+    getPath?: never;
+})): TelegramWorkspaceAdmissionRuntimeBinding;
 export declare function runWithTelegramWorkspaceAdmissions<T>(input: {
     ledger: Pick<TelegramWorkspaceAdmissionLedger, "acquireAdmission" | "releaseAdmission">;
     operationId: string;

package/node_modules/@llblab/pi-telegram/dist/lib/workspace-admission.js

@@ -7,8 +7,11 @@
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { getTelegramProcessLiveness, } from "./bus.js";
-import { renameTelegramPathWithRetry, withTelegramFileTransaction, } from "./locks.js";
+import { renameTelegramPathWithRetry, withTelegramFileTransaction, readTelegramRuntimeState, mutateTelegramRuntimeStateSection, TelegramRuntimeStateError, } from "./locks.js";
+import { areTelegramTargetsEqual as areTargetsEqual } from "./target.js";
+import { isWireRecord as isRecord, isNonNegativeWireInteger as isSafeTimestamp } from "./wire.js";
 const TELEGRAM_WORKSPACE_ADMISSION_VERSION = 1;
 const TELEGRAM_WORKSPACE_ADMISSION_MAX_LEASES = 4096;
 const TELEGRAM_WORKSPACE_ADMISSION_MAX_TEXT = 512;
@@ -71,12 +74,6 @@ function invalidState(message, cause) {
 function authorityChanged(message) {
     throw new TelegramWorkspaceAdmissionError("authority-changed", message);
 }
-function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-function isSafeTimestamp(value) {
-    return Number.isSafeInteger(value) && value >= 0;
-}
 function isBoundedText(value) {
     return (typeof value === "string" &&
         value.length > 0 &&
@@ -198,8 +195,9 @@ function normalizeFence(value, profileKey) {
     if (value.phase === "deletion-rejected" &&
         (value.destructiveKind === undefined || value.destructiveKind === "pressure-retirement") &&
         isSafeTimestamp(value.deletionIssuedAtMs) && isSafeTimestamp(value.rejectionConfirmedAtMs)) {
-        return { ...base, destructiveKind: value.destructiveKind, phase: "deletion-rejected",
-            deletionIssuedAtMs: value.deletionIssuedAtMs, rejectionConfirmedAtMs: value.rejectionConfirmedAtMs };
+        const { destructiveKind: _kind, ...pressureBase } = base;
+        return { ...pressureBase, ...(value.destructiveKind === "pressure-retirement" ? { destructiveKind: "pressure-retirement" } : {}),
+            phase: "deletion-rejected", deletionIssuedAtMs: value.deletionIssuedAtMs, rejectionConfirmedAtMs: value.rejectionConfirmedAtMs };
     }
     if (value.phase === "commit-ready" &&
         isSafeTimestamp(value.absenceConfirmedAtMs) &&
@@ -254,9 +252,34 @@ function readState(path, profileKey) {
     catch (error) {
         invalidState("Telegram Workspace admission state is malformed.", error);
     }
-    if (!isRecord(parsed)) {
-        invalidState("Telegram Workspace admission state is invalid.");
+    return normalizeAdmissionState(parsed, profileKey);
+}
+function isConsolidatedAdmissionKey(value, profile) {
+    if (!isBoundedText(value))
+        return false;
+    try {
+        const key = JSON.parse(value);
+        return isRecord(key) && Object.keys(key).length === 3 && key.version === TELEGRAM_WORKSPACE_ADMISSION_VERSION && key.profile === profile &&
+            isRecord(key.bot) && Object.keys(key.bot).length === 1 && typeof key.bot.tokenSha256 === "string" && /^[a-f0-9]{64}$/u.test(key.bot.tokenSha256);
     }
+    catch {
+        return false;
+    }
+}
+/** Pure damage check for one consolidated admission section under its own stored profile key; throws when invalid. */
+export function assertTelegramConsolidatedAdmissionSection(value, stateProfile) {
+    if (value === undefined)
+        return;
+    normalizeAdmissionState(value, isRecord(value) && typeof value.profileKey === "string" ? value.profileKey : "", stateProfile);
+}
+function normalizeAdmissionState(parsed, profileKey, stateProfile) {
+    if (parsed === undefined)
+        return { version: TELEGRAM_WORKSPACE_ADMISSION_VERSION, profileKey, leases: [] };
+    if (!isRecord(parsed))
+        invalidState("Telegram Workspace admission state is invalid.");
+    if (stateProfile !== undefined && (Object.keys(parsed).some(key => !["version", "profileKey", "leases", "fence", "writerProtocolMode"].includes(key)) ||
+        !isConsolidatedAdmissionKey(parsed.profileKey, stateProfile)))
+        invalidState("Telegram consolidated admission section identity is invalid.");
     if (parsed.version !== TELEGRAM_WORKSPACE_ADMISSION_VERSION ||
         !Array.isArray(parsed.leases) ||
         parsed.leases.length > TELEGRAM_WORKSPACE_ADMISSION_MAX_LEASES) {
@@ -291,6 +314,9 @@ function readState(path, profileKey) {
         invalidState("Telegram Workspace writer protocol mode is invalid.");
     if (fence && writerProtocolMode)
         invalidState("Telegram Workspace destructive fence conflicts with writer protocol mode.");
+    if (stateProfile !== undefined && (!isDeepStrictEqual(parsed.leases, normalizedLeases) ||
+        !isDeepStrictEqual(parsed.fence, fence) || !isDeepStrictEqual(parsed.writerProtocolMode, writerProtocolMode)))
+        invalidState("Telegram consolidated admission evidence cannot drop unknown fields.");
     return {
         version: TELEGRAM_WORKSPACE_ADMISSION_VERSION,
         profileKey,
@@ -331,9 +357,6 @@ function writeState(path, state, options) {
         }
     }
 }
-function areTargetsEqual(left, right) {
-    return left.chatId === right.chatId && left.threadId === right.threadId;
-}
 function scopesConflict(scope, target) {
     if (scope.kind === "profile")
         return true;
@@ -420,6 +443,8 @@ function validateOptions(options) {
     if (!normalizeOwner(options.owner)) {
         invalidInput("Telegram Workspace admission owner is invalid.");
     }
+    if (options.stateProfile !== undefined && (!isBoundedText(options.stateProfile) || !isConsolidatedAdmissionKey(options.profileKey, options.stateProfile)))
+        invalidInput("Telegram consolidated admission requires an exact bot/profile section identity.");
 }
 function validateOperationId(operationId) {
     if (!isBoundedText(operationId)) {
@@ -458,18 +483,22 @@ export function createTelegramWorkspaceAdmissionProfileKey(input) {
     });
 }
 export function createTelegramWorkspaceAdmissionRuntimeBinding(input) {
+    const { getProfileName, getBotToken, getPath, getStatePath } = input;
+    if ((getPath === undefined) === (getStatePath === undefined))
+        invalidInput("Telegram admission binding must select one storage identity.");
     return {
         resolve() {
-            const botToken = input.getBotToken();
+            const botToken = getBotToken();
             if (!botToken)
                 return undefined;
-            const configuredProfileName = input.getProfileName();
+            const configuredProfileName = getProfileName();
             const profileKey = createTelegramWorkspaceAdmissionProfileKey({
                 profileName: configuredProfileName ?? "default",
                 botToken,
             });
             return createTelegramWorkspaceAdmissionLedger({
-                path: input.getPath(configuredProfileName),
+                path: getStatePath ? getStatePath() : getPath(configuredProfileName),
+                ...(getStatePath ? { stateProfile: configuredProfileName ?? "default" } : {}),
                 profileKey,
                 owner: input.owner,
                 getNowMs: input.getNowMs,
@@ -651,11 +680,41 @@ export async function runWithTelegramWorkspaceAdmissionsAsync(input) {
 }
 export function createTelegramWorkspaceAdmissionLedger(options) {
     validateOptions(options);
+    const suppliedOptions = options;
+    if (options.stateProfile !== undefined)
+        options = { ...options, owner: { ...options.owner } };
     const getNowMs = options.getNowMs ?? Date.now;
     const getProcessLiveness = options.getProcessLiveness ??
         ((owner) => getTelegramProcessLiveness(owner));
     const transactionPath = `${options.path}.transaction`;
+    const path = options.path, profileKey = options.profileKey, stateProfile = options.stateProfile, boundOwner = { ...options.owner };
+    const publication = { publishRename: options.publishRename, onPublicationBoundary: options.onPublicationBoundary };
+    const isStorageCurrent = () => suppliedOptions.path === path && suppliedOptions.profileKey === profileKey &&
+        suppliedOptions.stateProfile === stateProfile && areOwnersEqual(suppliedOptions.owner, boundOwner);
+    const mapStateError = (error) => {
+        if (error instanceof TelegramRuntimeStateError)
+            throw new TelegramWorkspaceAdmissionError(error.code === "invalid" ? "invalid-state" : error.code, "Telegram consolidated admission state operation failed.", { cause: error });
+        throw error;
+    };
     function transact(operation) {
+        if (stateProfile !== undefined) {
+            try {
+                return mutateTelegramRuntimeStateSection(path, stateProfile, "admission", current => {
+                    const state = normalizeAdmissionState(current, profileKey, stateProfile);
+                    const retained = state.leases.filter(lease => getProcessLiveness(lease.owner) !== "dead");
+                    const pruned = retained.length !== state.leases.length;
+                    state.leases = retained;
+                    const outcome = operation(state);
+                    return { value: pruned || outcome.changed ? normalizeAdmissionState(state, profileKey, stateProfile) : current, result: outcome.result };
+                }, { isCurrent: isStorageCurrent, publishRename: publication.publishRename, onPublicationBoundary(boundary) {
+                        if (boundary !== "after-rename")
+                            publication.onPublicationBoundary?.(boundary, path);
+                    } });
+            }
+            catch (error) {
+                return mapStateError(error);
+            }
+        }
         return withTelegramFileTransaction(transactionPath, () => {
             const state = readState(options.path, options.profileKey);
             const retainedLeases = state.leases.filter((lease) => getProcessLiveness(lease.owner) !== "dead");
@@ -669,7 +728,23 @@ export function createTelegramWorkspaceAdmissionLedger(options) {
         });
     }
     function read() {
-        const state = readState(options.path, options.profileKey);
+        let state;
+        if (stateProfile !== undefined) {
+            if (!isStorageCurrent())
+                authorityChanged("Telegram consolidated admission storage authority changed.");
+            try {
+                const file = readTelegramRuntimeState(path);
+                const value = Object.hasOwn(file.profiles, stateProfile) ? file.profiles[stateProfile]?.admission : undefined;
+                state = normalizeAdmissionState(value, profileKey, stateProfile);
+                if (!isStorageCurrent())
+                    authorityChanged("Telegram consolidated admission storage authority changed.");
+            }
+            catch (error) {
+                return mapStateError(error);
+            }
+        }
+        else
+            state = readState(options.path, options.profileKey);
         return {
             profileKey: state.profileKey,
             leases: state.leases.map(cloneLease),
@@ -1151,8 +1226,8 @@ export function createTelegramWorkspaceAdmissionLedger(options) {
         return completeRetirementFence(expected, "manual-thread-cleanup");
     }
     return {
-        getProfileKey: () => options.profileKey,
-        getOwner: () => ({ ...options.owner }),
+        getProfileKey: () => stateProfile === undefined ? options.profileKey : profileKey,
+        getOwner: () => ({ ...(stateProfile === undefined ? options.owner : boundOwner) }),
         listReservedSlots: () => {
             const fence = read().fence;
             return fence && isTelegramWorkspaceRetirementFence(fence) ? [fence.slot] : [];

package/node_modules/@llblab/pi-telegram/dist/lib/workspace-identity.d.ts

@@ -0,0 +1,20 @@
+export interface TelegramWorkspaceBindingIdentity {
+    cwd: string;
+    workspaceKey: string;
+    /** Exact durable Pi session identity; absent only on legacy cwd-only bindings. */
+    sessionId?: string;
+    /** Full SHA-256 index component for session-qualified bindings. */
+    sessionKey?: string;
+    /** Immutable legacy binding-key component, not the displayed global letter. */
+    instanceSlot: string;
+    bindingKey: string;
+    /** Profile-wide letter reserved by the transient claim. */
+    slot?: string;
+}
+export declare const TELEGRAM_WORKSPACE_KEY_MAX_LENGTH = 180;
+export declare function normalizeTelegramSessionId(sessionId: string): string | undefined;
+export declare function createTelegramSessionKey(sessionId: string): string | undefined;
+export declare function normalizeTelegramWorkspacePath(cwd: string): string | undefined;
+export declare function createTelegramWorkspaceDirectoryKey(cwd: string): string | undefined;
+export declare function createTelegramWorkspaceBindingIdentityWithKey(cwd: string, workspaceKey: string, ordinal: number, sessionId?: string): TelegramWorkspaceBindingIdentity | undefined;
+export declare function createTelegramWorkspaceBindingIdentity(cwd: string, ordinal?: number, sessionId?: string): TelegramWorkspaceBindingIdentity | undefined;

package/node_modules/@llblab/pi-telegram/dist/lib/workspace-identity.js

@@ -0,0 +1,103 @@
+/**
+ * Durable Workspace identity value construction
+ * Zones: workspace identity, session identity, key encoding
+ * Owns exact session/CWD normalization, bounded keys and local instance-slot encoding.
+ * Excludes allocation, bindings/targets, storage-reference approval, custody and effects.
+ */
+import { createHash } from "node:crypto";
+import { posix, resolve } from "node:path";
+export const TELEGRAM_WORKSPACE_KEY_MAX_LENGTH = 180;
+const TELEGRAM_SESSION_ID_MAX_LENGTH = 256;
+export function normalizeTelegramSessionId(sessionId) {
+    if (typeof sessionId !== "string")
+        return undefined;
+    const normalized = sessionId.trim();
+    return normalized && Buffer.byteLength(normalized, "utf8") <=
+        TELEGRAM_SESSION_ID_MAX_LENGTH
+        ? normalized
+        : undefined;
+}
+export function createTelegramSessionKey(sessionId) {
+    const normalized = normalizeTelegramSessionId(sessionId);
+    return normalized
+        ? createHash("sha256").update(normalized).digest("hex")
+        : undefined;
+}
+export function normalizeTelegramWorkspacePath(cwd) {
+    const trimmed = cwd.trim();
+    if (!trimmed)
+        return undefined;
+    const normalized = (trimmed.startsWith("/")
+        ? posix.normalize(trimmed)
+        : resolve(trimmed).replaceAll("\\", "/"));
+    const withoutTrailingSeparators = normalized.length > 1 ? normalized.replace(/\/+$/u, "") : normalized;
+    return process.platform === "win32"
+        ? withoutTrailingSeparators.replace(/^([A-Z]):/u, (_, drive) => `${drive.toLowerCase()}:`)
+        : withoutTrailingSeparators;
+}
+export function createTelegramWorkspaceDirectoryKey(cwd) {
+    const normalized = normalizeTelegramWorkspacePath(cwd);
+    if (!normalized)
+        return undefined;
+    const readable = normalized
+        .replace(/[^\p{L}\p{N}._-]+/gu, "-")
+        .replace(/^-+|-+$/gu, "") || "root";
+    const candidate = `--${readable}--`;
+    if (candidate.length <= TELEGRAM_WORKSPACE_KEY_MAX_LENGTH)
+        return candidate;
+    const digest = createHash("sha256")
+        .update(normalized)
+        .digest("hex")
+        .slice(0, 12);
+    const prefixLength = TELEGRAM_WORKSPACE_KEY_MAX_LENGTH - digest.length - 5;
+    return `--${readable.slice(0, prefixLength)}-${digest}--`;
+}
+function createTelegramWorkspaceInstanceSlot(ordinal) {
+    if (!Number.isSafeInteger(ordinal) || ordinal < 0)
+        return undefined;
+    let value = ordinal + 1;
+    let slot = "";
+    while (value > 0) {
+        value -= 1;
+        slot = String.fromCharCode(97 + (value % 26)) + slot;
+        value = Math.floor(value / 26);
+    }
+    return slot;
+}
+export function createTelegramWorkspaceBindingIdentityWithKey(cwd, workspaceKey, ordinal, sessionId) {
+    const instanceSlot = createTelegramWorkspaceInstanceSlot(ordinal);
+    if (!instanceSlot)
+        return undefined;
+    const normalizedSessionId = sessionId === undefined
+        ? undefined
+        : normalizeTelegramSessionId(sessionId);
+    const sessionKey = normalizedSessionId
+        ? createTelegramSessionKey(normalizedSessionId)
+        : undefined;
+    if (sessionId !== undefined && (!normalizedSessionId || !sessionKey)) {
+        return undefined;
+    }
+    const legacyBindingKey = instanceSlot === "a"
+        ? workspaceKey
+        : `${workspaceKey}${instanceSlot}`;
+    return {
+        cwd,
+        workspaceKey,
+        ...(normalizedSessionId && sessionKey
+            ? { sessionId: normalizedSessionId, sessionKey }
+            : {}),
+        instanceSlot,
+        bindingKey: sessionKey
+            ? `${legacyBindingKey}-s-${sessionKey}`
+            : legacyBindingKey,
+    };
+}
+export function createTelegramWorkspaceBindingIdentity(cwd, ordinal = 0, sessionId) {
+    const normalized = normalizeTelegramWorkspacePath(cwd);
+    const workspaceKey = normalized
+        ? createTelegramWorkspaceDirectoryKey(normalized)
+        : undefined;
+    if (!normalized || !workspaceKey)
+        return undefined;
+    return createTelegramWorkspaceBindingIdentityWithKey(normalized, workspaceKey, ordinal, sessionId);
+}

package/node_modules/@llblab/pi-telegram/dist/lib/workspace-retirement.d.ts

@@ -4,10 +4,10 @@
  * Owns fail-closed protection, demand-driven pressure retirement, exact-intent admission,
  * successor recovery, and fenced one-shot deletion before durable slot reuse.
  */
-import type { TelegramUpdateJournalDeadQueueOwnerRecoveryInput, TelegramUpdateJournalDeadQueueOwnerRecoveryResult, TelegramUpdateJournalEntry, TelegramUpdateJournalQueueOwnerIdentity } from "./journal.ts";
-import type { TelegramTarget } from "./target.ts";
+import type { TelegramJournalNamespaceInspection, TelegramUpdateJournalDeadQueueOwnerRecoveryInput, TelegramUpdateJournalDeadQueueOwnerRecoveryResult, TelegramUpdateJournalEntry, TelegramUpdateJournalQueueOwnerIdentity } from "./journal.ts";
+import { type TelegramTarget } from "./target.ts";
 import { type TelegramWorkspaceThreadDeletionTransport } from "./telegram-api.ts";
-import type { TelegramTopicTargetStore, TelegramWorkspaceExternalProtectionEvidence, TelegramWorkspaceRetirementIntent, TelegramWorkspaceProtectionState, TelegramWorkspaceThreadBinding } from "./threads.ts";
+import type { TelegramTopicTargetStore, TelegramWorkspaceJournalSource, TelegramWorkspaceExternalProtectionEvidence, TelegramWorkspaceRetirementIntent, TelegramWorkspaceProtectionState, TelegramWorkspaceThreadBinding } from "./threads.ts";
 import { type TelegramWorkspaceAdmissionLedger, type TelegramWorkspaceAdmissionScope, type TelegramWorkspaceDeletionPermit } from "./workspace-admission.ts";
 export interface TelegramWorkspaceOperationGate {
     runExclusive: <T>(operation: () => Promise<T>) => Promise<T>;
@@ -36,18 +36,21 @@ interface TelegramWorkspaceJournalReader {
             entries: readonly {
                 update: unknown;
             }[];
+            exists?: boolean;
         };
     };
     readForProtection?: () => {
         entries: readonly {
             update: unknown;
         }[];
+        exists?: boolean;
     };
 }
 export declare function captureTelegramWorkspaceJournalProtectionSources(input: {
     binding: TelegramWorkspaceThreadBinding;
     resolveLeader: () => TelegramWorkspaceJournalReader | undefined;
     createFollowerResolver: (journalBindingKey: string) => () => TelegramWorkspaceJournalReader | undefined;
+    createSessionResolver?: (recipientBindingKey: string, sessionId: string) => () => TelegramWorkspaceJournalReader | undefined;
     withJournalReference?: <T>(binding: TelegramWorkspaceJournalReader, operation: () => T) => T;
     discovery?: {
         paths: readonly string[];
@@ -63,6 +66,7 @@ export type TelegramWorkspaceJournalProtectionSource = {
         kind: "binding";
         bindingKey: string;
         journalBindingKey: string;
+        sessionId?: string;
     } | {
         kind: "discovered";
         path: string;
@@ -70,6 +74,8 @@ export type TelegramWorkspaceJournalProtectionSource = {
     entries: readonly {
         update: unknown;
     }[];
+    /** Positive filesystem presence is distinct from a complete namespace with a missing historical family. */
+    exists?: boolean;
 } | {
     kind: "unknown";
     scope: {
@@ -78,6 +84,7 @@ export type TelegramWorkspaceJournalProtectionSource = {
         kind: "binding";
         bindingKey: string;
         journalBindingKey: string;
+        sessionId?: string;
     } | {
         kind: "discovered";
         path: string;
@@ -91,19 +98,24 @@ export declare function resolveTelegramWorkspaceAcceptedWorkProtection(input: {
     }[];
     journalSources: readonly TelegramWorkspaceJournalProtectionSource[];
     sourcesComplete: boolean;
+    /** Relocation cannot infer execution ownership from the original Telegram message target. */
+    requireBindingProvenance?: boolean;
 }): TelegramWorkspaceProtectionState;
 export type TelegramWorkspaceJournalPruneResult = {
     kind: "committed";
     binding: TelegramWorkspaceThreadBinding;
     removedKeys: string[];
+    removedSources?: TelegramWorkspaceJournalSource[];
 } | {
     kind: "blocked";
-    reason: "incomplete-evidence" | "writer-not-quiescent" | "state-changed";
+    reason: "incomplete-evidence" | "writer-not-quiescent" | "state-changed" | "publication-refused";
 };
 export declare function pruneTelegramWorkspaceJournalEvidence(input: {
-    store: Pick<TelegramTopicTargetStore, "commitWorkspaceJournalEvidence" | "persist">;
+    store: Pick<TelegramTopicTargetStore, "commitWorkspaceJournalEvidence" | "persistWorkspaceJournalEvidence">;
     binding: TelegramWorkspaceThreadBinding;
-    capture: TelegramWorkspaceJournalProtectionCapture;
+    /** Capture fresh source evidence after admission, not a snapshot taken before the lease. */
+    capture: () => TelegramWorkspaceJournalProtectionCapture;
+    runExclusive: TelegramWorkspaceOperationGate["runExclusive"];
     getJournalWriterProtection: (journalBindingKey: string) => TelegramWorkspaceProtectionState;
     getLeaderEpoch: () => number | string | undefined;
     getProfileKey: () => string;
@@ -113,6 +125,7 @@ export declare function pruneTelegramWorkspaceJournalEvidence(input: {
 }): Promise<TelegramWorkspaceJournalPruneResult>;
 export declare function captureTelegramWorkspaceExternalProtection(input: {
     binding: TelegramWorkspaceThreadBinding;
+    requireBindingProvenance?: boolean;
     getLiveOwnerProtection: (binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceProtectionState;
     getLocalAcceptedTargets: (binding: TelegramWorkspaceThreadBinding) => {
         targets: readonly TelegramTarget[];
@@ -121,7 +134,7 @@ export declare function captureTelegramWorkspaceExternalProtection(input: {
     captureJournalSources: (binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceJournalProtectionCapture;
     getDeliveryAuthorityProtection?: (binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceProtectionState;
 }): TelegramWorkspaceExternalProtectionEvidence;
-export declare function createTelegramWorkspaceExternalProtectionCapture(deps: {
+interface TelegramWorkspaceProtectionObserverDeps {
     listFollowers: () => readonly {
         target?: TelegramTarget;
     }[];
@@ -132,15 +145,35 @@ export declare function createTelegramWorkspaceExternalProtectionCapture(deps: {
     }[];
     resolveLeaderJournal: () => TelegramWorkspaceJournalReader | undefined;
     createFollowerJournalResolver: (journalBindingKey: string) => () => TelegramWorkspaceJournalReader | undefined;
+    createSessionJournalResolver?: (recipientBindingKey: string, sessionId: string) => () => TelegramWorkspaceJournalReader | undefined;
     discoverFollowerJournals?: () => {
         paths: readonly string[];
         complete: boolean;
     };
+    /** Strict read-only namespace evidence; it never substitutes for writer closure. */
+    inspectJournalNamespace?: () => TelegramJournalNamespaceInspection;
     createJournalPathResolver?: (path: string) => () => TelegramWorkspaceJournalReader | undefined;
     withJournalReference?: <T>(binding: TelegramWorkspaceJournalReader, operation: () => T) => T;
     getJournalWriterProtection?: (journalBindingKey: string) => TelegramWorkspaceProtectionState;
     getDeliveryAuthorityProtection?: (binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceProtectionState;
-}): (binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceExternalProtectionEvidence;
+}
+export interface TelegramWorkspaceProtectionObserver {
+    capture: (binding: TelegramWorkspaceThreadBinding, options?: {
+        requireBindingProvenance?: boolean;
+    }) => TelegramWorkspaceExternalProtectionEvidence;
+    captureJournalSources: (binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceJournalProtectionCapture;
+    getJournalWriterProtection: (journalBindingKey: string) => TelegramWorkspaceProtectionState;
+}
+/** Shared read-only observer: protection and metadata pruning use the same scoped evidence path. */
+export declare function createTelegramWorkspaceProtectionObserver(deps: TelegramWorkspaceProtectionObserverDeps): TelegramWorkspaceProtectionObserver;
+/** Callable protection view retained for callers that need no metadata observation ports. */
+export declare function createTelegramWorkspaceExternalProtectionCapture(deps: TelegramWorkspaceProtectionObserverDeps): TelegramWorkspaceProtectionObserver["capture"];
+export declare function createTelegramWorkspaceJournalEvidencePruner(deps: TelegramWorkspaceOperationGate & {
+    store: TelegramTopicTargetStore;
+    getAdmission: () => TelegramWorkspaceAdmissionLedger | undefined;
+    getLeaderEpoch: () => number | string | undefined;
+    protection: Pick<TelegramWorkspaceProtectionObserver, "captureJournalSources" | "getJournalWriterProtection">;
+}): (binding: TelegramWorkspaceThreadBinding, isCurrent: () => boolean) => Promise<TelegramWorkspaceJournalPruneResult>;
 export declare function isCurrentTelegramWorkspaceBinding(store: Pick<TelegramTopicTargetStore, "listWorkspaceBindings">, expected: TelegramWorkspaceThreadBinding): boolean;
 export interface TelegramWorkspaceDeadQueueJournalBinding {
     recoveryKey?: string;
@@ -175,6 +208,7 @@ export declare function createTelegramWorkspaceDeadOwnerQueueReclaimer(deps: {
     }[];
     resolveLeaderJournal: () => TelegramWorkspaceDeadQueueJournalBinding | undefined;
     createFollowerJournalResolver: (journalBindingKey: string) => () => TelegramWorkspaceDeadQueueJournalBinding | undefined;
+    createSessionJournalResolver?: (recipientBindingKey: string, sessionId: string) => () => TelegramWorkspaceDeadQueueJournalBinding | undefined;
     discoverFollowerJournals?: () => {
         paths: readonly string[];
         complete: boolean;
@@ -278,6 +312,7 @@ export type TelegramWorkspaceCapacityRunner = <T>(operation: () => Promise<T>) =
 export interface TelegramWorkspaceSlotRotationPorts extends TelegramWorkspaceOperationGate {
     getAdmission: () => TelegramWorkspaceAdmissionLedger | undefined;
     deleteThread: TelegramWorkspaceThreadDeletionTransport;
+    pruneJournalEvidence?: (binding: TelegramWorkspaceThreadBinding, isCurrent: () => boolean) => Promise<TelegramWorkspaceJournalPruneResult>;
     reclaimDeadOwnerQueuedWork?: (binding: TelegramWorkspaceThreadBinding, isCurrent: () => boolean) => Promise<TelegramWorkspaceDeadQueueReclamation>;
 }
 /** Retry allocation once, only after the failed operation released all ordinary leases. */