@llblab/pi-kit 0.27.5 → 0.28.0

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

@@ -17,7 +17,5 @@ export type TelegramInlineKeyboardButton = {
 export interface TelegramInlineKeyboardMarkup {
     inline_keyboard: TelegramInlineKeyboardButton[][];
 }
-export declare const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
-export declare function getTelegramCallbackDataByteLength(value: string): number;
 export declare function assertTelegramCallbackData(callbackData: string, context?: string): string;
 export declare function assertTelegramInlineKeyboardCallbackData(replyMarkup: unknown, context?: string): void;

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

@@ -3,8 +3,8 @@
  * Zones: telegram ui, shared structure
  * Owns the shared Bot API reply-markup shape while feature domains own their button semantics
  */
-export const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
-export function getTelegramCallbackDataByteLength(value) {
+const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
+function getTelegramCallbackDataByteLength(value) {
     return new TextEncoder().encode(value).byteLength;
 }
 export function assertTelegramCallbackData(callbackData, context = "Telegram callback_data") {

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

@@ -343,7 +343,7 @@ export function createTelegramCompactionObserverRuntime(deps) {
                 typingStartedByObserver = false;
                 deps.updateStatus(ctx);
                 deps.recordRuntimeEvent?.("compact", new Error("Compaction observer timed out"));
-                deps.onCompactionAbandoned?.();
+                // Observer expiry releases local presence, not Pi's eventual terminal result.
                 requestDispatch();
             }, timeoutMs);
             unrefTelegramLifecycleTimer(fallbackTimer);

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

@@ -1,7 +1,7 @@
 /**
  * Telegram singleton lock helpers
  * Zones: telegram ownership, filesystem, transport authority
- * Owns extension-local owners.json access and Telegram bridge ownership semantics
+ * Owns filesystem authority, atomic runtime-section publication and Telegram bridge ownership semantics
  */
 import { renameSync } from "node:fs";
 export declare const TELEGRAM_LOCK_KEY = "default";
@@ -14,10 +14,21 @@ export declare const TELEGRAM_OWNERSHIP_REFRESH_MS = 2000;
  * Named profile → the validated profile name
  */
 export declare function resolveTelegramLockKey(activeProfile?: string): string;
-export interface TelegramActiveProfileGetter {
+interface TelegramActiveProfileGetter {
     getActiveProfileName: () => string | undefined;
 }
 export declare function createTelegramLockKeyResolver(activeProfile: TelegramActiveProfileGetter): () => string;
+/** Structural session view; Locks never imports the lifecycle owner. */
+interface TelegramOwnedStateSessionPort<TContext extends TelegramLockContext> {
+    get: () => TContext | undefined;
+    getGeneration: () => number;
+    isCurrent: (ctx: TContext, generation?: number) => boolean;
+}
+/**
+ * Captures exact context, session generation and owned leader epoch before awaits.
+ * Session replacement, release or re-election revokes the grant; a successor never renews it.
+ */
+export declare function createTelegramOwnedStateAuthorityCapture<TContext extends TelegramLockContext>(lock: Pick<TelegramLockRuntime<TContext>, "owns" | "getOwnedLeaderEpoch">, session: TelegramOwnedStateSessionPort<TContext>): () => (() => boolean) | undefined;
 export interface TelegramLockEntry {
     pid: number;
     cwd?: string;
@@ -27,6 +38,8 @@ export interface TelegramLockEntry {
     runtimeGeneration?: number;
     busSocketPath?: string;
     busSecret?: string;
+    /** Polling journal custody; inherited by every successor and kept after release. */
+    journalPath?: string;
 }
 export interface TelegramLockContext {
     cwd: string;
@@ -43,12 +56,12 @@ export type TelegramLockState = {
     kind: "stale";
     lock: TelegramLockEntry;
 };
-export interface TelegramLockAcquireOptions {
+interface TelegramLockAcquireOptions {
     force?: boolean;
     expectedOwner?: TelegramLockEntry;
     election?: boolean;
 }
-export type TelegramLockAcquireResult = {
+type TelegramLockAcquireResult = {
     ok: true;
     lock: TelegramLockEntry;
     replacedStale: boolean;
@@ -56,6 +69,12 @@ export type TelegramLockAcquireResult = {
     ok: false;
     lock: TelegramLockEntry;
 };
+export type TelegramOwnedStatePublicationResult<T> = {
+    committed: false;
+} | {
+    committed: true;
+    result: T;
+};
 export interface TelegramLockRuntime<TContext extends TelegramLockContext> {
     acquire: (ctx: TContext, options?: TelegramLockAcquireOptions) => TelegramLockAcquireResult;
     release: () => TelegramLockState;
@@ -64,17 +83,26 @@ export interface TelegramLockRuntime<TContext extends TelegramLockContext> {
     getOwnedLeaderEpoch: () => number | string | undefined;
     owns: (ctx?: TelegramLockContext) => boolean;
     commitIfOwned: (commit: () => void) => boolean;
+    /** Consolidated-store publication; domain reducers retain their own exact payload/CAS rules. */
+    publishStateSectionIfOwned?: <T>(section: "workspace" | "runtime", mutate: (current: unknown, observed: Readonly<TelegramRuntimeStateProfile>) => TelegramRuntimeStateMutation<T>, options: TelegramOwnedStatePublicationOptions) => TelegramOwnedStatePublicationResult<T>;
     refresh: (ctx?: TelegramLockContext) => boolean;
+    /** The polling journal named by owners.json for this key, owned or not. */
+    getJournalPath: () => string | undefined;
 }
-export interface TelegramLockOwnershipGuard<TContext extends TelegramLockContext> {
+interface TelegramLockOwnershipGuard<TContext extends TelegramLockContext> {
     ownsContext: (ctx: TContext) => boolean;
 }
-export interface TelegramLockContextStore<TContext extends TelegramLockContext> {
+interface TelegramLockContextStore<TContext extends TelegramLockContext> {
     get: () => TContext | undefined;
 }
-export interface TelegramLockRuntimeOptions {
+interface TelegramLockRuntimeOptions {
     key?: string | (() => string | undefined);
     locksPath?: string;
+    /** Consolidated version-2 state envelope; exclusive with `locksPath`. */
+    statePath?: string;
+    statePublication?: Pick<TelegramRuntimeStatePublicationOptions, "onPublicationBoundary" | "publishRename">;
+    /** Read-only ownership file of releases that used another directory; a live fresh owner there blocks acquisition. */
+    legacyLocksPath?: string;
     pid?: number;
     isProcessAlive?: (pid: number) => boolean;
     instanceId?: string;
@@ -84,9 +112,25 @@ export interface TelegramLockRuntimeOptions {
     mintLeaderEpoch?: () => number | string;
     runtimeGeneration?: number;
     staleHeartbeatMs?: number;
+    /** First leader without an inherited pointer names the polling journal it creates. */
+    createJournalPath?: (ctx: TelegramLockContext) => string | undefined;
 }
+/**
+ * Leader polling journal: the path owners.json names, else the session that would host it on acquisition.
+ * Without a session identity, the flat root `inbox` remains the compatibility fallback.
+ */
+export declare function createTelegramLeaderJournalPathResolver(deps: {
+    getNamedJournalPath: () => string | undefined;
+    getSessionId: () => string | undefined;
+    getProfileName: () => string | undefined;
+}): {
+    createJournalPath: () => string | undefined;
+    resolve(profileName?: string): string;
+};
+/** A released key keeps only `{ journalPath }`: no owner, but the successor's polling custody. */
+export declare function readTelegramLockJournalPath(value: unknown): string | undefined;
 export declare function readLocks(path?: string): Record<string, unknown>;
-export interface TelegramRenameRetryOptions {
+interface TelegramRenameRetryOptions {
     rename?: typeof renameSync;
     attempts?: number;
     retryDelayMs?: number;
@@ -100,17 +144,56 @@ export interface TelegramFileTransactionOptions {
     retryDelayMs?: number;
 }
 export declare function withTelegramFileTransaction<T>(transactionPath: string, operation: () => T, options?: TelegramFileTransactionOptions): T;
+export type TelegramRuntimeStateSection = "transport" | "workspace" | "admission" | "runtime";
+type TelegramRuntimeStateProfile = Partial<Record<TelegramRuntimeStateSection, unknown>>;
+interface TelegramRuntimeStateFile {
+    version: 2;
+    profiles: Record<string, TelegramRuntimeStateProfile>;
+}
+export declare class TelegramRuntimeStateError extends Error {
+    readonly code: "invalid" | "authority-changed" | "publication-unknown";
+    constructor(code: TelegramRuntimeStateError["code"], message: string, options?: ErrorOptions);
+}
+/** Strict, observational envelope read; section owners validate their own payloads. Legacy state is never adopted here. */
+export declare function readTelegramRuntimeState(path: string): TelegramRuntimeStateFile;
+/**
+ * Operator-approved optimistic recovery before leader acquisition: when the shared envelope, any transport section or a
+ * caller-validated section is damaged, publish a fresh empty envelope instead of refusing. All profiles lose runtime
+ * continuity. Filesystem access errors are not damage and still throw. Returns whether a reset was published.
+ */
+export declare function resetDamagedTelegramRuntimeState(path: string, validateProfile?: (profile: string, sections: Readonly<TelegramRuntimeStateProfile>) => void): boolean;
+export interface TelegramRuntimeStateMutation<T> {
+    value: unknown;
+    result: T;
+}
+interface TelegramRuntimeStatePublicationOptions {
+    /** Exact domain authority, recaptured by the caller before invoking this synchronous transaction. */
+    isCurrent: () => boolean;
+    onPublicationBoundary?: (boundary: "before-write" | "after-write-before-rename" | "after-rename") => void;
+    publishRename?: typeof renameSync;
+}
+export interface TelegramOwnedStatePublicationOptions extends TelegramRuntimeStatePublicationOptions {
+    /** Optional caller-bound physical/logical identity; a mismatch cannot redirect an owner grant. */
+    expectedScope?: {
+        path: string;
+        profile: string;
+    };
+}
+/**
+ * One physical read/check/write transaction for one named section. The caller supplies domain policy; copies expose
+ * current sibling facts without granting writes to them. No await, nested transaction, repair or legacy import.
+ */
+export declare function mutateTelegramRuntimeStateSection<T>(path: string, profile: string, section: TelegramRuntimeStateSection, mutate: (current: unknown, observed: Readonly<TelegramRuntimeStateProfile>) => TelegramRuntimeStateMutation<T>, options: TelegramRuntimeStatePublicationOptions): T;
 export declare function writeLocks(path: string, locks: Record<string, unknown>): void;
 export declare function parseTelegramLockEntry(value: unknown): TelegramLockEntry | undefined;
 export declare function isProcessAlive(pid: number): boolean;
-export declare function formatTelegramLockEntry(lock: TelegramLockEntry): string;
 export declare function createTelegramLockRuntime<TContext extends TelegramLockContext>(options?: TelegramLockRuntimeOptions): TelegramLockRuntime<TContext>;
 export declare function createTelegramLockOwnershipGuard<TContext extends TelegramLockContext>(lock: TelegramLockRuntime<TContext>): TelegramLockOwnershipGuard<TContext>;
 export declare function createTelegramDirectDeliveryOwnershipChecker<TContext extends TelegramLockContext>(deps: {
     lock: TelegramLockRuntime<TContext>;
     contextStore: TelegramLockContextStore<TContext>;
 }): () => boolean;
-export interface TelegramLockedPollingStartOptions {
+interface TelegramLockedPollingStartOptions {
     force?: boolean;
     forceFreshLeaderThread?: boolean;
     requestedThreadName?: string;
@@ -119,7 +202,7 @@ export interface TelegramLockedPollingStartOptions {
     };
     onAcquired?: () => Promise<void> | void;
 }
-export type TelegramLockedPollingStartResult = {
+type TelegramLockedPollingStartResult = {
     ok: true;
     message?: string;
     canTakeover?: false;
@@ -134,14 +217,18 @@ export interface TelegramLockedPollingRuntime<TContext extends TelegramLockConte
     stop: () => Promise<string>;
     suspend: () => Promise<void>;
     isSuspended: () => boolean;
+    /** Fence one owned polling generation; suspension, restart, conflict or lock loss revokes it. */
+    captureTransportAuthority: (ctx: TContext) => (() => boolean) | undefined;
     onPersistentConflict: (ctx: TContext, count: number) => Promise<void>;
     onSessionStart: (_event: unknown, ctx: TContext) => Promise<void>;
     registerFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
     restoreFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
     stopFollowerRegistration?: () => void;
 }
-export interface TelegramLockedPollingRuntimeDeps<TContext extends TelegramLockContext> {
+interface TelegramLockedPollingRuntimeDeps<TContext extends TelegramLockContext> {
     lock: TelegramLockRuntime<TContext>;
+    /** Optimistically replaces a damaged shared runtime state before a non-election acquisition. */
+    resetDamagedState?: () => boolean;
     hasBotToken: () => boolean;
     getBotTokenDiagnostic?: () => string | undefined;
     canStartPolling?: (ctx: TContext) => boolean;
@@ -163,3 +250,4 @@ export interface TelegramLockedPollingRuntimeDeps<TContext extends TelegramLockC
     ownershipRefreshMs?: number;
 }
 export declare function createTelegramLockedPollingRuntime<TContext extends TelegramLockContext>(deps: TelegramLockedPollingRuntimeDeps<TContext>): TelegramLockedPollingRuntime<TContext>;
+export {};