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

package/dist/git-repository-host.d.ts

@@ -1,38 +1,154 @@
-import { type RepoIdentityEntry, type RepoState, type RepositoryTransportLayout } from "@amalgm/live";
+import { type BigIntStats } from "node:fs";
+import { type EntityType, type RepoIdentityEntry, type RepoIdentityMap, type RepoState, type RepositoryTransportLayout } from "@amalgm/live";
+import { type LiteralRepositoryView, type LiteralStats, type ProvenMembers } from "./git-literal-host.js";
+import type { LiteralLane } from "./content-capture-pool.js";
+import { type RevealGround } from "./git-literal-replay.js";
+import { type PreparedLiteralCheckpoint } from "./git-checkpoint-preparation.js";
+import { type CheckpointWorkingFile } from "./git-checkpoint-construction.js";
 import { type DurableFile } from "./durability-barrier.js";
+import type { GitConfigurationObservation } from "./git-configuration.js";
+import { GitCapture } from "./git-capture.js";
+import { type SourceProof } from "./source-proof.js";
+/** One observation of a directory's `.git` entry. */
+export interface GitMarker {
+    readonly physicalKey: string;
+    readonly kind: "directory" | "file" | "other";
+}
+/** What one lstat of a `.git` entry says. */
+export declare const gitMarker: (marker: BigIntStats) => GitMarker;
+/** The `.git` entry as it stands now; null when absent. */
+export declare function observeGitMarker(directory: string): GitMarker | null;
 /** Classification observes only the filesystem marker. Git command health
  * belongs to Card + Checkpoint capture and cannot demote repository ground. */
-export declare function hasGitMarker(directory: string): boolean;
+export declare const marksRepository: (marker: GitMarker | null) => boolean;
+export declare const hasGitMarker: (directory: string) => boolean;
+/** The nested repositories a reading of `identity`'s repository must not enter. */
 export declare function nestedRepositoryPaths(identity: readonly RepoIdentityEntry[]): string[];
 export declare function markRepositoryReveal(repository: string): void;
 export declare function repositoryRevealInProgress(repository: string): boolean;
+/** One collected repository moment and the proof its owner must close. */
+export interface ObservedRepository {
+    readonly capture: GitCapture;
+    readonly state: RepoState;
+    readonly view: LiteralRepositoryView;
+    readonly configuration: GitConfigurationObservation;
+    readonly proof: SourceProof;
+}
+/** Physical observation for publication. Selection and package sealing have
+ * not happened; the caller retains this source proof, unclosed, and its
+ * admission closes it once. */
+export declare function observeRepositoryForPublication(capture: GitCapture, identity: readonly RepoIdentityEntry[], lane: LiteralLane, proven: ProvenMembers): Promise<ObservedRepository>;
+/** Seal an observation when publication selected every observed member. No
+ * second Git/worktree observation is necessary; the original proof still
+ * closes once, at admission. */
+export declare function captureObservedRepository(observed: ObservedRepository, identity: readonly RepoIdentityEntry[], observedIdentity: RepoIdentityMap, prior: PriorRepositoryTransport | null, previousIdentity: RepoIdentityMap | null): Promise<CapturedRepositoryTransport>;
 export interface PriorRepositoryTransport {
     readonly stateId: string;
     readonly transportVersion: string;
     readonly card: RepoState["card"];
     readonly identityHash: string;
 }
+/** Content-addressed cache bytes are evidence, not ground. A cached head that
+ * cannot prove the row's declared state is a cache miss, never a Detect fault. */
+export declare function readPriorRepositoryTransport(cacheDir: string, row: {
+    readonly type: string;
+    readonly payloadVersion: string | null;
+    readonly transportVersion: string | null;
+} | null | undefined): Promise<PriorRepositoryTransport | null>;
+/** A fresh local observation, distinct from a hash computed for comparison.
+ * The original source proof travels with the pair into Record's admission. */
+export interface RepositoryObservationPair {
+    readonly uuid: string;
+    readonly absolutePath: string;
+    readonly payloadVersion: string;
+    readonly gitConfigurationObservation: string | null;
+    readonly physicalKey: string;
+    readonly filesystemMode: number;
+    readonly proof: SourceProof;
+}
+export declare function pairRepositoryObservation(uuid: string, directory: string, observed: ObservedRepository, identityHash: string): RepositoryObservationPair;
 export interface CapturedRepositoryTransport extends PriorRepositoryTransport {
+    readonly capture: GitCapture;
+    readonly configuration: GitConfigurationObservation;
     readonly state: RepoState;
+    readonly view: LiteralRepositoryView;
     /** Identity sealed into this exact transport. Checkpoint untracked bytes
      * are the payload witness for their matching UUID entries. */
-    readonly identity: readonly RepoIdentityEntry[];
+    readonly identity: RepoIdentityMap;
     /** null means the prior immutable transport is already the exact result. */
     readonly bytes: Uint8Array | null;
+    /** Unclosed: the caller's admission closes it once. */
+    readonly proof: SourceProof;
+}
+/** One physical repository moment: Card + Checkpoint and the worktree
+ * namespace beneath one set of nested-repository boundaries. It names no
+ * identity, so every record Apply compares in one phase is judged from the
+ * same reading. Observing costs Card + Checkpoint reads, never a pack. */
+export interface RepositoryReading {
+    readonly repository: string;
+    readonly boundaries: readonly string[];
+    readonly state: RepoState;
+    readonly view: LiteralRepositoryView;
+    readonly configuration: GitConfigurationObservation;
+    /** Every worktree member outside Git storage and Amalgm control. */
+    readonly members: ReadonlyMap<string, RepositoryMember>;
+    /** Closed when read. A later decision that trusts it closes it again. */
+    readonly proof: SourceProof;
 }
-/** The semantic moment one repository is in: what Apply compares against a
- * record. Observing costs Card + Checkpoint reads and never builds a pack. */
-export type RepositoryObservation = Pick<RepoState, "stateId" | "card">;
-export declare function observeRepository(repository: string, identity: readonly RepoIdentityEntry[]): RepositoryObservation;
+/** A nested boundary is never entered; any other Git marker is a repository
+ * no identity can admit as ordinary ground. */
+type RepositoryMember = {
+    readonly kind: "boundary";
+    readonly directory: boolean;
+} | {
+    readonly kind: "repository";
+} | {
+    readonly kind: "directory";
+    readonly stats: BigIntStats;
+} | {
+    readonly kind: "leaf";
+};
+/** One reading judged against one identity: what Apply compares against a
+ * record. The expected identity's state holds only expected untracked
+ * members; the complete observed payload also holds the local remainder
+ * policy keeps unshared. */
+export interface RepositoryObservation {
+    readonly stateId: string;
+    readonly identityHash: string;
+    /** Every expected member is present, and every other worktree member is
+     * accounted remainder that stays untracked and keeps its recorded type.
+     * Remainder is never required: its absence is only a fresh observation. */
+    readonly identityMatches: boolean;
+    readonly observedPayload: string;
+    /** Remainder still present, with fresh payloads and stats. */
+    readonly remainder: readonly RemainderObservation[];
+    readonly proof: SourceProof;
+    /** The complete observed payload paired with this moment's Git
+     * configuration, for the O row an owner writes for `uuid` at `directory`. */
+    pair(uuid: string, directory: string): RepositoryObservationPair;
+}
+export interface RemainderObservation {
+    readonly entry: RepoIdentityEntry;
+    readonly stats: LiteralStats | BigIntStats;
+}
+export declare function readRepository(repository: string, boundaries: readonly string[], lane: LiteralLane, ownReveal?: boolean): Promise<RepositoryReading>;
+/** Judge one reading against one identity and the remainder it may keep.
+ * Remainder is accounted one member at a time, never by an excluded
+ * ancestor: it must keep its type and stay outside Git's index. */
+export declare function judgeRepository(reading: RepositoryReading, identity: readonly RepoIdentityEntry[], remainder: readonly RepoIdentityEntry[]): RepositoryObservation;
 /** One observed repository moment reproduces one immutable transport exactly
- * when its state, Card and identity map all agree with it. */
+ * when its complete Git state and identity map agree with it. */
 export declare function repositoryObservationMatches(observed: RepositoryObservation, identity: readonly RepoIdentityEntry[], prior: PriorRepositoryTransport): boolean;
-/** Card + Checkpoint are the complete physical Git state. Callers that must
- * also prove the transport's entity frontier use repositoryObservationMatches. */
-export declare function repositoryObservationMatchesState(observed: RepositoryObservation, prior: Pick<PriorRepositoryTransport, "stateId" | "card">): boolean;
-/** Capture one semantic repository state. A chainable capture packs only Git
- * objects absent from its parent and only changed identity-map paths. */
-export declare function captureRepository(repository: string, identity: readonly RepoIdentityEntry[], prior: PriorRepositoryTransport | null, previousIdentity?: readonly RepoIdentityEntry[] | null): CapturedRepositoryTransport;
+/** A selected member's bytes with the type they classify as. */
+export interface SelectedRepositoryLeaf extends CheckpointWorkingFile {
+    readonly type: Extract<EntityType, "file.text" | "file.binary" | "link">;
+}
+/** Compile the selected working files over the observed native Git history,
+ * index and continuation. Retained members keep their advertised content
+ * witnesses; immutable byte sources never become physical stat evidence.
+ * Every other selected member is read once, on a content thread, and must
+ * reproduce the type and payload its entry declares. */
+export declare function captureSelectedRepository(observed: ObservedRepository, identity: readonly RepoIdentityEntry[], retained: ReadonlyMap<string, SelectedRepositoryLeaf>, lane: LiteralLane, prior: PriorRepositoryTransport | null, previousIdentity: RepoIdentityMap | null): Promise<CapturedRepositoryTransport>;
 export interface AppliedRepositoryState {
     readonly stateId: string;
     readonly cardId: string;
@@ -41,25 +157,35 @@ export interface AppliedRepositoryState {
     readonly transportVersion: string;
     readonly identity: readonly RepoIdentityEntry[];
     readonly durableFiles: readonly DurableFile[];
+    /** The closed readback that proved the reveal, for Verify to consume. */
+    readonly reading: RepositoryReading;
 }
-/** Materialize a complete transport chain and then re-derive its semantic
- * state. The oldest node must be self-contained; every later node must name
- * the exact predecessor whose Git objects and identity map it extends. */
-export declare function applyRepository(repository: string, chain: readonly Uint8Array[]): AppliedRepositoryState;
 export interface SealedRepositoryTransport {
     readonly file: string;
     readonly transportVersion: string;
 }
-export declare function inspectRepositoryTransportFile(file: string): RepositoryTransportLayout;
+/** A transport's layout from its header alone; the pack and Checkpoint
+ * bytes it locates are never read. */
+export declare function inspectRepositoryTransportFile(file: string): Promise<RepositoryTransportLayout>;
 /** Seal the compact full identity frontier beside the current transport. The
  * evidence is disposable, but its content is accepted only when its hash
  * equals the immutable transport header that names it. */
-export declare function sealCachedRepositoryIdentity(cacheDir: string, transportVersion: string, identity: readonly RepoIdentityEntry[], identityHash: string): void;
+export declare function sealCachedRepositoryIdentity(cacheDir: string, transportVersion: string, identity: RepoIdentityMap, identityHash: string): Promise<void>;
 /** Reconstruct the exact identity map named by one cached immutable
  * repository transport. Compact sealed evidence survives ancestor-pack
  * pruning; without it, a complete cached chain is replayed once and seals the
  * frontier. No mutable entity row can substitute for either proof. */
-export declare function readCachedRepositoryIdentity(cacheDir: string, transportVersion: string): readonly RepoIdentityEntry[] | null;
+export declare function readCachedRepositoryIdentity(cacheDir: string, transportVersion: string): Promise<RepoIdentityMap | null>;
+/** Recover retained working bytes from their immutable transport chain. This
+ * owns private Git objects only; it never checks out files or touches the live
+ * repository, its index, refs, or metadata. The caller must close the result. */
+export declare function prepareRepositoryFiles(chain: readonly SealedRepositoryTransport[]): Promise<{
+    readonly layout: RepositoryTransportLayout;
+    readonly identity: readonly RepoIdentityEntry[];
+    readonly checkpoint: PreparedLiteralCheckpoint;
+    close(): Promise<void>;
+}>;
 /** Apply sealed repository artifacts by streaming each Git range directly
  * into index-pack. Download already verified each complete transport hash. */
-export declare function applyRepositoryFiles(repository: string, chain: readonly SealedRepositoryTransport[]): Promise<AppliedRepositoryState>;
+export declare function applyRepositoryFiles(repository: string, chain: readonly SealedRepositoryTransport[], ground: RevealGround): Promise<AppliedRepositoryState>;
+export {};