@amalgm/shell 0.1.164-preview.36072132286 → 0.1.164-preview.36809057014

package/dist/content-capture-pool.d.ts

@@ -0,0 +1,287 @@
+/**
+ * Content capture and cache sealing run on a small pool of worker threads.
+ *
+ * Capture is the expensive part of Detect: every byte is read and hashed
+ * twice (whole-file and per-block identity), and a sealing capture stages
+ * the bytes for the immutable cache. Sealing held bytes verifies, hashes and
+ * stages them. None of that may occupy the one thread that schedules Watch,
+ * Detect admission, Apply and Send. Like Syncthing's hashers, a fixed number
+ * of content threads work in parallel, all started with the ground; the main
+ * thread only dispatches and receives results. The capture and publication
+ * laws stay in content-cache-host; literal repository reads stay in
+ * git-literal-read. What
+ * a reply staged is published on the main thread, after the group barrier
+ * that makes it durable, so a content thread never waits for a drive flush:
+ * before its caller resumes, or, for a pass's capture, when the pass names
+ * its whole set (cargo-group.ts).
+ *
+ * Complete-lane work is bulk: a whole-root walk can queue
+ * thousands of jobs. Every other job answers one edit. Service is fair, not
+ * only prioritized: waiting bulk work always holds one thread, so a steady
+ * stream of edits never starves a whole-root pass; edits take every other
+ * thread first, and bulk never holds the last one. With one thread the two alternate while both
+ * wait, so an edit waits for at most one bounded bulk job.
+ *
+ * A physical close is judged here too: the witnesses an admission retained
+ * are sampled again and compared, so the admitting thread never re-reads
+ * ground. Only what a witness cannot carry — host authority and checks over
+ * live objects — stays with the admission that runs on the main thread.
+ *
+ * Identity discovery runs on one more thread of its own, in arrival order:
+ * the listings it retains live in that thread, so every discovery finds
+ * them, and no capture or examination ever waits behind one.
+ *
+ * A repository's ground subtrees are read here too, in one read transaction,
+ * so no read of a whole territory waits on the drive on the main thread, as
+ * is what a root's changed sharing policy newly includes.
+ *
+ * So is every replay built from sealed cache bytes: a text result's delta or
+ * snapshot and a link's target. A cache read can wait behind the cache
+ * directory's full flush, and the main thread never waits on a drive.
+ *
+ * A thread that read a ground file keeps its connection to it
+ * (detection/thread-database.ts). Releasing that file reaches every live
+ * thread, each after the job it is running (ground-holders.ts).
+ */
+import type { ContentManifest, LinkReplay, TextReplay, TransferArtifact } from "@amalgm/live";
+import type { IdentityDiscovery, IdentityDiscoveryResult } from "./detection/identity-discovery.js";
+import type { CachedReplayRequest } from "./detection/portable.js";
+import type { GroundInventory, TerritoryRead } from "./ground-basis.js";
+import type { RootExamination, RootExaminationResult, RootMaintenance, RootMaintenanceResult } from "./detection/root-examination.js";
+import { type GitHostPin } from "./git-command.js";
+import type { LiteralBatch, LiteralRequest } from "./git-literal-read.js";
+import type { SourceWitness } from "./source-witness.js";
+import { type CargoGroup } from "./cargo-group.js";
+import { type CacheCapture, type CacheStage, type CapturedFileContent } from "./content-cache-host.js";
+import { type CaptureFailure } from "./content-failure.js";
+import { type SourceProof } from "./source-proof.js";
+import type { SourceStat } from "./source-signature.js";
+/** One capture as it crosses to a worker. The expected stat is plain data. */
+export interface CaptureJob {
+    readonly kind: "capture";
+    readonly id: number;
+    readonly sourceFile: string;
+    readonly expected: SourceStat;
+    readonly cacheDir: string | null;
+    readonly collect: boolean;
+}
+/** Held bytes to seal. The worker owns `bytes`: they were transferred. */
+export interface SealJob {
+    readonly kind: "seal";
+    readonly id: number;
+    readonly cacheDir: string;
+    readonly artifact: TransferArtifact;
+    readonly bytes: Uint8Array;
+}
+/** Rebuild a lost or invalid manifest hint from retained cache bytes. */
+export interface DeriveJob {
+    readonly kind: "derive";
+    readonly id: number;
+    readonly cacheDir: string;
+    readonly artifact: TransferArtifact;
+}
+/** Literal reads of one repository's working paths, at most one bounded batch. */
+export interface LiteralJob {
+    readonly kind: "literal";
+    readonly id: number;
+    readonly repository: string;
+    readonly format: string;
+    readonly requests: readonly LiteralRequest[];
+}
+/** One complete examination of a quiet root, or one maintenance visit of a
+ * root, through the dispatcher's Git. */
+export interface ExamineJob {
+    readonly kind: "examine";
+    readonly id: number;
+    readonly examination: RootExamination | RootMaintenance;
+    readonly git: GitHostPin;
+}
+/** Where some identities stand in one root's namespace. */
+export interface DiscoverJob {
+    readonly kind: "discover";
+    readonly id: number;
+    readonly discovery: IdentityDiscovery;
+}
+/** Retained witnesses to judge: one list per proof leaf, each in order. */
+export interface CloseJob {
+    readonly kind: "close";
+    readonly id: number;
+    readonly leaves: readonly (readonly SourceWitness[])[];
+}
+/** One repository's subtrees in the inventories asked, from one ground file. */
+export interface TerritoryJob {
+    readonly kind: "territory";
+    readonly id: number;
+    readonly database: string;
+    readonly uuid: string;
+    readonly inventories: readonly GroundInventory[];
+}
+/** Where one root's committed sharing is not yet its selection under a
+ * sharing policy, with the bindings whose declarations selection holds. */
+export interface OwedJob {
+    readonly kind: "owed";
+    readonly id: number;
+    readonly database: string;
+    readonly rootUUID: string;
+    readonly policy: string;
+    readonly bindingDir: string;
+}
+/** One text or link replay, built from the sealed cache bytes it names. */
+export interface ReplayJob {
+    readonly kind: "replay";
+    readonly id: number;
+    readonly cacheDir: string;
+    readonly request: CachedReplayRequest;
+}
+/** Close this thread's connection to one ground file. */
+export interface ReleaseJob {
+    readonly kind: "release";
+    readonly id: number;
+    readonly database: string;
+}
+export type ContentJob = CaptureJob | SealJob | DeriveJob | LiteralJob | ExamineJob | DiscoverJob | CloseJob | TerritoryJob | OwedJob | ReplayJob | ReleaseJob;
+/** CPU the capture thread itself spent on one job, in microseconds. */
+export interface CaptureCpu {
+    readonly user: number;
+    readonly system: number;
+}
+export type ContentReply = {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly captured: CacheCapture;
+    readonly collected: ArrayBuffer | null;
+} | {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly sealed: CacheStage;
+} | {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly manifest: ContentManifest;
+} | {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly literal: LiteralBatch;
+} | {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly examined: RootExaminationResult | RootMaintenanceResult;
+    readonly gitSpawns: readonly unknown[];
+} | {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly discovered: IdentityDiscoveryResult;
+} | {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly closed: readonly (CaptureFailure | null)[];
+} | {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly territories: TerritoryRead;
+} | {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly owed: readonly string[];
+} | {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly replay: TextReplay | LinkReplay;
+} | {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly released: string;
+} | {
+    readonly id: number;
+    readonly cpu: CaptureCpu;
+    readonly failure: CaptureFailure;
+};
+/** Which Detect lane asked: queue time is reported per lane. */
+export type CaptureLane = "named" | "complete";
+/** Apply's Verify reads literal leaves too; it is never bulk. */
+export type LiteralLane = CaptureLane | "apply";
+/** Who asked for a seal: queue and run time are reported per origin. */
+export type SealOrigin = "detect-link" | "repository" | "apply" | "intentional";
+/** A capture's result; `collected` holds the exact bytes read when asked. */
+export interface PooledCapture extends CapturedFileContent {
+    readonly collected: Buffer | null;
+}
+/** Start every content thread before any edit can need one: a thread boots
+ * in tens of milliseconds, which no edit may wait for. */
+export declare function startContentThreads(): void;
+/**
+ * Capture one stable file on a content thread: fingerprint check, one read
+ * feeding whole and block identity, text/binary evidence, and — with a cache
+ * directory — the immutable seal, named before this resolves unless a pass's
+ * `cargo` group holds it. `collect` returns the exact bytes read so a fused
+ * caller never reads the file again.
+ */
+export declare function captureContent(sourceFile: string, expected: SourceStat, cacheDir: string | null, options: {
+    readonly lane: CaptureLane;
+    readonly collect?: boolean;
+    readonly cargo?: CargoGroup;
+}): Promise<PooledCapture>;
+/**
+ * Seal held bytes in the machine content cache on a content thread: verify
+ * them against the artifact, publish them only over durable bytes, and leave
+ * their manifest as a hint. Resolves once the name is published, unless a
+ * pass's `cargo` group holds it; directory durability stays with the caller
+ * that commits a reference to it.
+ */
+export declare function sealContent(cacheDir: string, artifact: TransferArtifact, bytes: Uint8Array, origin: SealOrigin, cargo?: CargoGroup): Promise<void>;
+/**
+ * The manifest of a sealed artifact: its hint when that is exactly valid,
+ * otherwise derived again on a content thread from the retained bytes. A
+ * lost or corrupt hint therefore never fails a reader.
+ */
+export declare function contentManifest(cacheDir: string, artifact: TransferArtifact): Promise<ContentManifest>;
+/**
+ * One bounded batch of literal repository reads on a content thread. The
+ * answers name what was read and its components; requests beyond the batch's
+ * byte bound return unread for another batch.
+ */
+export declare function readLiteral(repository: string, format: string, requests: readonly LiteralRequest[], lane: LiteralLane): Promise<LiteralBatch>;
+/**
+ * Examine one quiet root on a content thread: disk, O and Git compared by
+ * the same laws as the main walk, answering unchanged with what admission
+ * needs, or the first difference. Bulk work: edits never wait behind it.
+ */
+export declare function examineRootContent(examination: RootExamination): Promise<RootExaminationResult>;
+/**
+ * Judge retained witnesses on a content thread, one verdict per proof leaf:
+ * null when every witness still holds, else the first that does not. The
+ * leaf's admission, if any, remains the caller's.
+ */
+export declare function judgeSourceWitnesses(leaves: readonly (readonly SourceWitness[])[], lane: CaptureLane): Promise<readonly (CaptureFailure | null)[]>;
+/** One proof's physical close, its witnesses judged on a content thread and
+ * then its admission, which only this thread can answer, run here. */
+export declare function closePhysicallyOffThread(proof: SourceProof, lane: CaptureLane): Promise<void>;
+/**
+ * The replay of one sealed text or link result, read from the cache and
+ * verified on a content thread. Complete-lane replays are bulk work.
+ */
+export declare function replayCachedContent(cacheDir: string, request: CachedReplayRequest, lane: CaptureLane): Promise<TextReplay | LinkReplay>;
+/**
+ * Where some identities stand in one root's namespace, read on the discovery
+ * thread with its retained listings; a gap when it cannot say.
+ */
+export declare function discoverRootIdentities(discovery: IdentityDiscovery): Promise<IdentityDiscoveryResult>;
+/**
+ * One repository's subtrees in the inventories asked, read in one transaction
+ * on a content thread with the incarnation and sequence it read. An edit
+ * waits on it, so it never queues as bulk.
+ */
+export declare function readGroundTerritories(database: string, uuid: string, inventories: readonly GroundInventory[]): Promise<TerritoryRead>;
+/**
+ * The root-relative addresses, outermost only, where one root's committed
+ * sharing is not yet its selection under `policy`, read on a content thread.
+ * The caller awaits the save that made the policy current, so every earlier
+ * admission is read.
+ */
+export declare function readOwedAddresses(database: string, rootUUID: string, policy: string, bindingDir: string): Promise<readonly string[]>;
+/**
+ * Visit one root on a content thread for maintenance: the same walk and
+ * comparison against O, answering with what differs and what it could not
+ * read. It concludes nothing. Bulk work: edits never wait behind it.
+ */
+export declare function maintainRootContent(maintenance: RootMaintenance): Promise<RootMaintenanceResult>;