@amalgm/shell 0.1.164-main.39921181499 → 0.1.164-main.40054498467

package/PURPOSE.md

@@ -24,8 +24,13 @@ the sharing baseline, and the last verified materialization. Existing effect
 recovery must finish before this shortcut can resolve history. This boundary
 is being implemented; the full native Apply examination has not passed it yet.
 
-One read-only view of bound, nonterminal Apply recovery receipts protects original
-participants and source/destination cones during Detect. Root and path coverage
+One read-only view of the open Apply windows, bound and not yet ended, protects
+every address, object and entity their receipt rows name during Detect
+(`src/detection/apply-ownership.ts`). The window's receipt is its row, never a
+file: bound before the first visible effect, ended at Verify, durable only after
+the revealed bytes are flushed (`src/apply-window-saves.ts`); every reveal step
+is idempotent against it, so a window re-entered after a crash runs the same
+steps again (`src/apply-window-recovery.ts`). Root and path coverage
 remain distinct from ownership: the walk leaves each owned cone unread inside its
 root and admits the root's independent units; only a cone containing the root, or
 Register and first-login declaration, defer the whole root. No deferred row is
@@ -208,8 +213,9 @@ effect remains. Every remaining effect passes the same local-work, preimage
 and destination checks under the complete ground scope. An interrupted effect
 owns a recovery obligation, never arbitrary later edits at its address. Recovery
 cannot be retired until its retained versions have an explicit safe disposition.
-Startup may settle history through an explicitly installed snapshot watermark;
-equality with a sharing row never manufactures a current materialization proof.
+Only verified materialization settles history: Verify, or an Add's install of
+exactly the entities it verified present or absent. Equality with a sharing row
+never manufactures a current materialization proof.
 The exact Apply outcome commits before private recovery deletion. The same
 intent then owns only a finite cleanup description; restart dispatches that
 responsibility without current O or old cargo. Cleanup hashes survivors with
@@ -428,16 +434,23 @@ Each requests F_FULLFSYNC where the platform has it, because a plain macOS fsync
 can leave a commit in the drive's cache. Every write to a ground file is a
 named save run by that file's one saver thread (`src/ground-saver.ts`): saves
 posted while a commit flushes form the next batch, each in its own savepoint,
-committed once at synchronous=FULL. A save settles only once the drive holds
-it, so Send submits only durable Outbox rows; the main thread's ground
-connections only read, so it never waits for the drive. Detect reports the
-journal, synchronous and fullfsync settings the saver committed under.
+committed once. A save settles only once the drive holds it, except an
+ordered save whose truth also stands elsewhere (Detect's admission, a stamp,
+a received page): it commits without waiting for the drive, and the next
+strict commit's flush covers it, because the log only grows. Send asks for
+that flush before every offer, so it submits only durable Outbox rows; the
+main thread's ground connections only read, so it never waits for the drive.
+Detect reports the journal, synchronous and fullfsync settings the saver's
+strict commits run under.
 Whatever launches the runtime process names the Node flags of
 `src/runtime-node-flags.ts`: a bounded young generation keeps each of the main
 thread's garbage-collection pauses to a few milliseconds.
-Durability acknowledgements require the native flush to succeed through a handle
-with the access it requires; a failed flush cannot become a successful install
-or materialization. Each writer owns the durability of the files it creates.
+Every file and directory flush is the operating system's own, through Node
+(`src/flush.ts`): fsync, FlushFileBuffers on Windows, F_FULLFSYNC on macOS.
+There is no weaker flush, so a write that must persist before another is
+flushed before the other is issued. Durability acknowledgements require that
+flush to succeed through a handle with the access it requires; a failed flush
+cannot become a successful install or materialization. Each writer owns the durability of the files it creates.
 Content equality alone cannot acknowledge durable materialization; Verify
 re-establishes the affected file and directory flushes before completion.
 The staging barrier composes a writer's acknowledgement only while its exact
@@ -558,7 +571,10 @@ Local profiles retain their selected sources and do not follow managed targets.
    separation, installation verification, restart proof, and readiness. Its
    Files step returns explicit paused evidence or calls one `@amalgm/live`
    user-ground convergence operation. The shell supplies filesystem, SQLite,
-   Watch, and cloud-wire effects only. Resume retains the existing recovery,
+   Watch, and cloud-wire effects only. Joining ground takes its place in one
+   save that discharges what produced it (initial-publication.ts); ground
+   already on the delivery line keeps its own position, and no startup jumps
+   it to a newer head. Resume retains the existing recovery,
    Watch and Detect/Record order to reconcile a stopped or paused interval.
 
 10. **One wire reaches the existing authority.** The shell's Live adapter uses
@@ -862,21 +878,24 @@ after adoption.
     entity identity. Missing, corrupt, or obsolete cache bytes are removed and
     recomputed from authoritative local ground; they never become a legacy
     compatibility requirement and never prevent the machine from resuming.
-    A cache name appears only over durable bytes: every writer makes a staged
-    file durable before renaming it into place, so an existing name already
+    A cache name appears only over durable bytes: every writer flushes a
+    staged file before renaming it into place, so an existing name already
     holds that immutable object and a rename over it replaces identical
     durable bytes. Windows refuses to replace a name another holder has
     open; that name is judged as one found before staging, adopted only when
-    it qualifies. Staged cargo becomes durable in groups: its bytes are
-    written through to the device, and one barrier covers every writer that
-    staged before the barrier began (on macOS, one drive flush), so a burst of
-    captures never waits for one full flush per file. A barrier stalls the
-    staging still in flight, so a pass that captures a set names it together
-    once the whole set has staged, as Git batches object writes behind one
-    flush: one barrier per pass, and none while its reads run. Before Record admits
-    captured cargo it flushes the cache directories off the event loop only
-    when a required name is not yet known durable; a crash can lose an
-    unrecorded name, never leave a Record naming torn bytes.
+    it qualifies. A staged file is flushed when it is named, not when it is
+    written: a pass that captures a set names the cargo its Records carry once
+    the whole set has staged and removes the rest unflushed, so its reads
+    never wait on the drive. A Record and its cargo become durable together.
+    The small cargo a named pass read commits in its Record's own
+    transaction, so the log's order is its durability and the pass pays no
+    flush; the cache names it afterward, and the journal lets it go only once
+    the name is durable. Send reads the journal first; any other reader of an
+    unnamed name finds it absent, which it already answers (a delta base
+    selects the snapshot). Any other cargo is named before its Record commits,
+    with one flush of the cache directory, off the event loop, and none when
+    every required name is already known flushed. A crash can lose an
+    unrecorded name, never leave a Record whose bytes stand nowhere.
     A pending Send consults its capture-derived manifest and the authority's
     immutable inventory before opening local cargo: after upload succeeded but
     before its acknowledgement became durable, complete cloud cargo is enough
@@ -992,17 +1011,18 @@ after adoption.
     A graph that `add` has just materialized and verified is the initial
     baseline for that newly covered root, so Watch does not report the
     downloader's own writes as user edits; every later OS notification remains
-    ordinary suspicion. The same verified notebook is Apply's materialization
-    baseline: the newest retained Inbox result that exactly equals each
-    installed row advances that entity's resolved and materialized sequence
-    without replaying historical cargo, while every later different result
-    remains ordinary Apply work. Watch may establish native coverage before
-    startup Apply is ready, but its suspicions remain unconsumed until Apply
-    has adopted or resumed durable materialization. Startup adopts that
-    baseline while holding every watched ground cone; only after Apply starts
-    does one Detect generation consume the rings accumulated during boot. An
-    older Detect transaction settles first and any newer Watch generation
-    waits until adoption finishes. Register
+    ordinary suspicion. The same verified install is Apply's materialization
+    baseline, committed with its rows: each installed entity resolves through
+    its last received record within the watermark, materialized at that record
+    when the install verified exactly its version, and each set-aside member,
+    verified absent, resolves at the same place, materialized nowhere
+    (`src/apply-window-saves.ts`). Every other received
+    record, including every later record of those entities, remains ordinary
+    Apply work, and the Add wakes Apply's line once it releases its ground.
+    Watch may establish native coverage before startup Apply is ready, but its
+    suspicions remain unconsumed until Apply has acquired its binding roots and
+    resumed durable materialization; only after Apply starts does one Detect
+    generation consume the rings accumulated during boot. Register
     and Watch enumerate the same durable binding inventory, so a missed
     notification for rendering the portable reference cannot lose a
     declaration. A bound root that no Register has committed is held: it is
@@ -1112,8 +1132,13 @@ after adoption.
 35. **Container membership is version input, never cargo.** A workspace or
     folder derives its logical version from the UUIDs and names of active
     direct children, while its portable and notebook `payloadVersion` remains
-    null. Every Shell writer stores only the derived version, and Live's cloud
-    codec refuses a container payload. An independently ordered container
+    null. Every Shell writer stores only the derived version: each save that
+    changes membership derives it inside its own transaction from the children
+    that inventory records, so a child no save has recorded counts nowhere,
+    no row comparison counts a container's version, and no proof holds it: a
+    proof holds where a container stands and the slot it takes, so a sibling
+    recorded meanwhile never stales it. Live's cloud codec refuses
+    a container payload. An independently ordered container
     receipt may therefore create, move, or rename its address, but it can never
     overwrite membership already established by child UUID rows or emit a
     second container mutation for that derivation. Local adapter evidence can
@@ -1337,8 +1362,18 @@ after adoption.
 53. **Visible ground coordinates by address cone.** Detect, Register, Add, Add
     recovery, and Apply each name the directory cones their filesystem plus
     SQLite projection effects touch, and two effects wait for each other only
-    when one cone contains the other. A Detect pass holds exactly the roots it
-    observes; Register holds its coverage family and core reference ground;
+    when one cone contains the other. A Detect pass leases exactly the ground
+    it reads, and only ground no effect holds: a name under a held cone stays
+    owed while its root's other names proceed, and a release rings Detect as
+    a write rings Watch, so that name looks again once its ground is free.
+    Every lane, the complete lane included, gates on the ground its cut reads
+    by one law: each name's subtree from its top (the first address the
+    index does not hold as a folder), or the repository that owns it, with
+    the root's policy file. Ground a proof finds it reads beyond that (Git
+    storage a checkout keeps elsewhere, a frame's folders, a root's whole
+    namespace) it takes only while no effect holds it; held, a named proof
+    waits for that ground and a complete-lane cut waits as its complete root.
+    Register holds its coverage family and core reference ground;
     Add holds its destination, staging, and core ground; Apply's final guard
     holds its target address, the entity's current address, and any addresses
     a repository identity map relocates. Conflicting effects are served in
@@ -1415,9 +1450,11 @@ after adoption.
     phases service Watch and transport; it inserts no scheduling gap between
     a final guard and reveal. This does not bound a single synchronous effect.
     A visible repository rewrite carries
-    `.git/amalgm-reveal` from its first Git mutation until exact Verify; Detect
-    treats that marker as unsettled private Apply ground, and restart resumes the
-    same durable intent before the marker is removed. Incremental materialization
+    `.git/amalgm-reveal`, naming its attempt, from its first Git mutation until
+    its readback proves the result, and restart resumes the same durable intent
+    before the marker is removed. Only that attempt's recovery reads the marker:
+    Detect leaves the repository unread because the attempt's receipt owns the
+    ground, and a marker no receipt owns holds nothing. Incremental materialization
     imports only transport ranges whose declared Git tips are absent locally.
     Gaining or losing `.git` keeps the containing UUID and changes only its
     type rail.
@@ -1483,8 +1520,10 @@ after adoption.
     every committed delivery prefix is reconstructible and Add never selects
     a graph the parcel law would not publish. Replay closure also owes a
     deletion nothing else states, because the repository whose package held
-    it stopped being a live one, together with its enclosing ancestors that
-    have no head. The first
+    it stopped being a live one. Whatever it owes carries each enclosing
+    ancestor up to the first that travels after the batch or is already owed:
+    an ancestor's own head is no proof, since a later package may have
+    superseded it. The first
     later record on an entity UUID establishes its immediate entity predecessor
     from the complete snapshot prefix, after which ordinary dense per-entity gap
     checking resumes. A publisher may name only the exact locally received
@@ -1670,8 +1709,9 @@ after adoption.
     is examined or remains explicitly pending. A named single-consumer result
     closes the complete original binding and exclusion proof at Record.
 
-    Changed native source evidence and Amalgm's own incomplete reveal refuse
-    capture; the mere existence of a Git lock does not. A stable
+    Changed native source evidence refuses capture; the mere existence of a
+    Git lock or a reveal marker does not. Amalgm's own incomplete reveal is
+    ground its receipt owns, which Detect leaves unread (law 54). A stable
     unfinished merge is portable Checkpoint truth: Shell captures its
     unmerged stages, worktree conflict bytes, and merge continuation through
     Live's one repository contract, and restores ordinary stages only after
@@ -1831,15 +1871,18 @@ releasing narrow leases, then yields: the complete examination starts in its
 own dispatcher activation and reads a new basis over the wider scope. Later
 notices retain their own cutoffs. Failure, deferral and repeated widening
 cannot replenish foreground priority. Every examination may reuse proven
-content: a leaf is reused only while its signature is unchanged and both its
-times precede the boundary of a content clock stamped on the root's own
+content: a leaf is reused only while its signature is unchanged and its
+change time precedes the boundary of a content clock stamped on the root's own
 filesystem in `.amalgm/content-clock` before the reads (`content-clock.ts`).
-The boundary is the stamp less its profile's margin; a time with no
-subsecond part stands for its whole second. A racy leaf is reread; only that
-reread clears it. A stamp behind the root's previous one, or under another
-profile than the previous stamp names, retires every proof under the root;
-a conclusion drawn before that retirement at, above or beneath the root fails
-its admission and is read again, and a unit that consumed an identity
+The boundary is the stamp's change time less its profile's margin; a time
+with no subsecond part stands for its whole second. A racy leaf is reread;
+only that reread clears it. Every proof names the root's qualification it was
+stamped under, and a root shows only proofs under its own. A stamp under another
+profile, or behind the latest boundary a kept proof stands on, requalifies the
+root in one write of the root, never of its rows, so no stamp file restored
+from an old copy can revive a proof; a conclusion drawn before that at, above
+or beneath the root fails its admission and is read again, and a unit that
+consumed an identity
 discovery reads and stands on that discovery's whole scope.
 Directory listings close on the same rule: a racy listing names no complete
 membership until a fresh listing under a later stamp, and only filesystems
@@ -1851,7 +1894,7 @@ clock ticks escapes that, and each such move is a later Watch generation.
 The control tree carries a `.gitignore` of `*`, written once per root per
 process when absent or different, so a registered repository's Git status
 never shows it. Ground without a qualified clock (another device, a root that
-cannot hold a stamp, a clock that went backwards) is read by every
+cannot hold a stamp) is read by every
 examination and closes each listing by reading it again: it loses shortcuts,
 never conclusions. Qualifying further filesystems, NTFS and ReFS among them,
 is unfinished.
@@ -1890,7 +1933,12 @@ are pending; this setting grants no performance pass.
 
 Fresh observation reads mutable content without copying unchanged files into
 the cache. Only selected new content is sealed before Record, against the same
-original physical proof. Cache existence or size alone is never content proof.
+original physical proof. A leaf that publishes on its own channel is selected
+even when Git tracked it: the read that seals its observed bytes also names
+their Git object, and its record states the exact SHA-256 value while its
+repository's package keeps the Git object. A trashed leaf known only by its
+Git object stays unsealed; Restore, which would need its bytes, is not built.
+Cache existence or size alone is never content proof.
 Source reads refuse special-file substitutions without waiting for another
 process, and release every owned resource even when another cleanup fails.
 Git parcel reuse requires equal fresh worktree and Card evidence. The Card's

package/dist/accepted-fold.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The accepted fold: a committed head H at watermark M with every statement
+ * the authority accepted in (M, N], resolved by Live's one reducer.
+ *
+ * H is paged per root, and nothing reads the whole account. A statement acts
+ * only on rows in the roots it reaches: the root H held its entity in, the
+ * root H held its parent in, and, through a parent the tail itself states,
+ * every root that parent reaches. Roots joined this way form a component.
+ * Folding a component's statements, in acceptance order, onto its roots'
+ * records is the whole fold restricted to those roots, because no statement
+ * outside the component reads or writes a row inside it. A parent that H
+ * does not place and no statement yet states can only be a member some
+ * package places, in any root, so its statement joins every root. A join
+ * wider than the fold needs is still exact: what it adds folds untouched.
+ *
+ * The fold is held (Reduction): advancing it through later statements folds
+ * only those, onto each component's reduction, and that is the fold of the
+ * whole tail at once. A join keeps a reduction only when the other side
+ * adds no base rows and no statement the reduction has passed; otherwise
+ * the joined component opens again from its roots. A component folds when a
+ * reader asks for a row in it. Its rows return to their final roots by
+ * parent chain, and every root it loaded answers, empty when nothing stays
+ * in it. A root no statement reaches is H's own.
+ *
+ * H traveled when it was published, so an unreached root travels as H holds
+ * it, and a reached one rejudges only the territories its fold touched.
+ */
+import { type CloudEntityRecord, type EntityStatement, type FoldOfHead, type RepositoryIdentityPort, type Sha256Hex } from "@amalgm/live";
+import type { RegistryGraph } from "./registry-graph.js";
+/** Where the fold holds one identity: its final root and resolved row. */
+export interface AcceptedRecord {
+    readonly root: string;
+    readonly record: CloudEntityRecord;
+}
+export declare class AcceptedFold {
+    #private;
+    readonly graph: RegistryGraph;
+    readonly repositoryIdentity: RepositoryIdentityPort;
+    private readonly sha256Hex;
+    private constructor();
+    /** Join `statements` into components over `graph`'s roots. Nothing folds
+     * until a reader asks for a root the statements reach. */
+    static open(graph: RegistryGraph, statements: readonly EntityStatement[], repositoryIdentity: RepositoryIdentityPort, sha256Hex: Sha256Hex): Promise<AcceptedFold>;
+    /** Take the statements accepted next, in acceptance order. */
+    advance(statements: readonly EntityStatement[]): Promise<void>;
+    /** One root's resolved rows, unprojected. */
+    root(rootId: string): Promise<readonly CloudEntityRecord[]>;
+    /** One root's resolved rows as they travel. */
+    traveling(rootId: string): Promise<readonly CloudEntityRecord[]>;
+    /** The subtree `uuid` heads after the fold, as it travels; empty when the
+     * fold holds no row for it. A row's verdict reads only its nearest
+     * repository's territory, which lies beneath that repository, so the
+     * projection reads the subtree of the nearest repository above `uuid`,
+     * or `uuid`'s own, and nothing else in its root. */
+    travelingSubtree(uuid: string): Promise<readonly CloudEntityRecord[]>;
+    /** Where the fold holds `uuid`, or null when it holds no row for it. */
+    locate(uuid: string): Promise<AcceptedRecord | null>;
+    /** Every root's own row after the fold: the discovery set. Only a root's
+     * own statement creates, changes or demotes it, since a package drops rows
+     * only beneath its repository, so only the components such statements join
+     * resolve. */
+    rootRecords(): Promise<readonly CloudEntityRecord[]>;
+    /** Every root a statement reaches, after the fold: what a head through N
+     * must rebuild so it never names a watermark it has not applied. */
+    reached(): Promise<readonly string[]>;
+    private componentOf;
+    /** The root H holds `uuid` in, asked of H once. */
+    private where;
+    private partition;
+    /** The component's reduction through all its statements. */
+    private resolve;
+    /** Fold the statements the reduction has not passed, opening it from the
+     * component's roots when there is none. A fold that fails leaves the
+     * reduction half-folded, so it is dropped. */
+    private fold;
+}
+/** A resolved graph (an accepted fold, or ground installed from one) as it
+ * travels, projected in the host's turns. `fold` names what a fold of a
+ * published head touched. */
+export declare function travelingInTurns(records: readonly CloudEntityRecord[], sha256Hex: Sha256Hex, repositoryIdentity: RepositoryIdentityPort, fold?: FoldOfHead): Promise<readonly CloudEntityRecord[]>;
+/** Ground this computer captured as it travels, in the host's turns: the
+ * rows it states on their own channels, each repository's package stating
+ * the rest. Structure alone, so no package is read and a disk spelling Git
+ * never saw cannot reach the graph. */
+export declare function capturedInTurns(records: readonly CloudEntityRecord[], sha256Hex: Sha256Hex): Promise<readonly CloudEntityRecord[]>;