instar 1.3.1600 → 1.3.1601

package/dist/core/AppMediaReplicator.d.ts

@@ -0,0 +1,241 @@
+import type { AppMediaStore } from './AppMediaStore.js';
+import type { AppConversationStore } from './AppConversationStore.js';
+export declare const APP_MEDIA_SLICE_BYTES: number;
+export declare const MAX_SERVES_AT_ONCE = 2;
+export declare const PULL_TICK_MS = 5000;
+export declare const SLICES_PER_TICK = 8;
+export declare const LOAD_PAUSE_MAX_MS: number;
+export declare const BACKOFF_MIN_MS = 30000;
+export declare const BACKOFF_MAX_MS: number;
+export declare const GIVE_UP_MS: number;
+export declare const PEER_FAILURES_TO_OPEN = 5;
+export declare const PEER_OPEN_MS: number;
+export declare const PEER_OPENS_TO_LATCH = 3;
+export declare const INVENTORY_EVERY_MS: number;
+export declare const INVENTORY_FRESH_MS: number;
+export declare const INVENTORY_PAGE = 5000;
+export declare const INVENTORY_MAX_PAGES = 50;
+export declare const NUDGE_MAX = 500;
+export declare const SINGLE_COPY_GRACE_MS: number;
+export declare const SINGLE_COPY_OFFLINE_MS: number;
+export declare const UNMEASURABLE_ALARM_MS: number;
+/** The owner waits this long for missing blobs before dispatching with "still copying" (§4.12). */
+export declare const OWNER_PULL_WAIT_MS = 60000;
+/** A "still copying" row older than this becomes a "could not be copied" line. */
+export declare const PENDING_DELIVERY_TTL_MS: number;
+/** The app-media-path helper waits this long for a pull (§4.5). */
+export declare const MEDIA_PATH_WAIT_MS = 30000;
+/** The mesh verb. One verb, three operations, all read/observe class. */
+export type AppMediaPullCommand = {
+    type: 'app-media-pull';
+    op: 'slice' | 'inventory' | 'nudge';
+    sha256?: string;
+    offset?: number;
+    /** inventory: the version the asker already holds (answer `unchanged` or a diff). */
+    since?: string;
+    /** inventory: page cursor (hashes strictly after this one). */
+    after?: string;
+    /** nudge: hashes the asker holds alone. */
+    hashes?: string[];
+};
+export type SliceAnswer = {
+    ok: true;
+    size: number;
+    offset: number;
+    dataB64: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export type InventoryAnswer = {
+    ok: true;
+    version: string;
+    unchanged: true;
+} | {
+    ok: true;
+    version: string;
+    diff: {
+        added: string[];
+        removed: string[];
+    };
+} | {
+    ok: true;
+    version: string;
+    full: true;
+    hashes: string[];
+    next: string | null;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface MeshSendResult {
+    ok: boolean;
+    status?: number;
+    result?: unknown;
+    reason?: string;
+}
+export interface AppMediaTransport {
+    /** Every registered peer (never this machine); `online: null` when unknown. */
+    peers: () => Array<{
+        machineId: string;
+        nickname?: string;
+        online: boolean | null;
+    }>;
+    send: (machineId: string, command: AppMediaPullCommand, timeoutMs: number) => Promise<MeshSendResult>;
+    /** This machine's load verdict (trustworthy-machine-load); absent ⇒ never paused for load. */
+    loadVerdict?: () => string;
+}
+export interface AppMediaReplicatorDeps {
+    media: AppMediaStore;
+    store: AppConversationStore;
+    selfId: () => string;
+    now?: () => number;
+    report?: (detail: string) => void;
+    raiseAttention?: (item: {
+        conditionKey: string;
+        title: string;
+        body: string;
+    }) => void;
+    clearAttention?: (conditionKey: string) => void;
+    /** A blob landed on this machine (pending "still copying" rows resolve here). */
+    onBlobLanded?: (sha: string) => void;
+}
+export declare class AppMediaReplicator {
+    private readonly d;
+    private transport;
+    private readonly now;
+    private readonly db;
+    private serving;
+    private ticking;
+    private wanted;
+    private wantedAt;
+    private wantedDirty;
+    /** On-demand pulls (a download, app-media-path, an owner dispatch) go first and ignore the load pause. */
+    private readonly priority;
+    private readonly waiters;
+    private readonly peerCursor;
+    /** The one peer each partial copy comes from (§ blame, above). In memory: after a restart a part with no known source is restarted. */
+    private readonly partPeer;
+    /** When an on-demand ask or a nudge last skipped this file's backoff (at most once per backoff window). */
+    private readonly lastHurryAt;
+    private readonly peerInventories;
+    private ownInventories;
+    private loadPausedSince;
+    private lastInventoryRound;
+    private inventoryRunning;
+    private singleSince;
+    private nudgedAt;
+    private unmeasurableSince;
+    /** First time each held hash was seen held alone (the 24 h offline-peer rule). */
+    private readonly singleFirstSeen;
+    /** Notice latch: one notice per condition episode, re-armed only when the condition clears. */
+    private readonly raised;
+    private tickTimer;
+    readonly counters: {
+        slicesServed: number;
+        slicesPulled: number;
+        blobsLanded: number;
+        verifyFailures: number;
+        busyRefusals: number;
+        nudgesSent: number;
+    };
+    constructor(d: AppMediaReplicatorDeps);
+    attachTransport(t: AppMediaTransport | null): void;
+    hasTransport(): boolean;
+    start(): void;
+    stop(): void;
+    private report;
+    /** New events landed (replication or a local send): the wanted list is recomputed on the next tick. */
+    markWantedDirty(hashes?: readonly string[]): void;
+    private rearm;
+    serve(raw: unknown): Promise<SliceAnswer | InventoryAnswer | {
+        ok: true;
+        queued: number;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /** Unpurged references from any event this machine holds (live or deleted conversations). */
+    private referenced;
+    private serveSlice;
+    /** This machine's held, unpurged hashes; recomputed at most every 5 minutes, last 3 versions kept for diffs. */
+    ownInventory(): {
+        version: string;
+        hashes: string[];
+    };
+    private serveInventory;
+    private serveNudge;
+    /** Referenced, unpurged hashes this machine does not hold. Cached for a minute (or until dirty). */
+    private wantedHashes;
+    private partPath;
+    private removePart;
+    private pullRow;
+    isUnrecoverable(sha: string): boolean;
+    /** Ask for this blob now (download, app-media-path, owner dispatch). */
+    want(sha: string): void;
+    /**
+     * Skip a file's backoff for one immediate attempt, at most once per backoff window: an app
+     * polling a download every 2 s, or repeated nudges, can never turn the backoff into a hot loop.
+     */
+    private hurry;
+    /** Whether an on-demand copy can start now; otherwise the plain reason (the download route's 202 vs 404). */
+    canFetch(sha: string): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /** Online peers with a closed breaker that could hold this file (a fresh inventory that lacks it rules a peer out). */
+    private candidatePeers;
+    private noPeerReason;
+    /** On-demand asks waiting for a blob right now (observability and tests). */
+    waiterCount(): number;
+    /** Resolve true when the blob is held, or false after `ms` (the pull keeps going in the background). */
+    awaitBlob(sha: string, ms: number): Promise<boolean>;
+    /** Why a blob is not here yet, in plain words (app-media-path's message). */
+    whyNotHere(sha: string): string;
+    private settleWaiters;
+    /** One pull tick. Single-flight; never throws. */
+    tick(): Promise<void>;
+    /** How many slices this tick may move for background (non-priority) pulls. */
+    private backgroundBudget;
+    private runTick;
+    private peerChoice;
+    private advancePeer;
+    private pullOneSlice;
+    /** Hash the complete part in a worker; keep it only if length and SHA-256 equal the reference. */
+    private finishPart;
+    /** The file stopped being wanted mid-copy (purged): its partial copy and pull state go, waiters hear no. */
+    private dropUnreferenced;
+    private landed;
+    /** Backoff 30 s → 1 h; unrecoverable after 7 days with no peer serving it. */
+    private blobFailure;
+    private peerRow;
+    breakerOpen(id: string, t?: number): boolean;
+    private verifyFailure;
+    private peerSuccess;
+    /** Fetch every online peer's inventory (diff when possible), then evaluate the alarms. */
+    inventoryRound(): Promise<void>;
+    private fetchInventory;
+    /**
+     * Held, unpurged blobs no peer inventory younger than 2 hours lists. `count: null` (never 0)
+     * when that cannot be measured: no mesh transport, or a peer whose inventory is old or missing.
+     */
+    singleCopy(): {
+        count: number | null;
+        hashes: string[];
+        reason: string | null;
+    };
+    private unrecoverableCount;
+    private conversationsOf;
+    /** The single-copy alarm ladder (§4.12). Called after each inventory round. */
+    evaluateAlarms(): void;
+    /** One notice per machine while blobs are unrecoverable (§4.12). */
+    evaluateUnrecoverable(): void;
+    /** Raise once per condition and reason; a new reason refreshes the same item. */
+    private raiseOnce;
+    private clearNotice;
+    /** Observability for tests and /health. */
+    status(): Record<string, unknown>;
+}
+//# sourceMappingURL=AppMediaReplicator.d.ts.map

package/dist/core/AppMediaReplicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppMediaReplicator.d.ts","sourceRoot":"","sources":["../../src/core/AppMediaReplicator.ts"],"names":[],"mappings":"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"}