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

package/dist/watching/fsevents.d.ts

@@ -1,2 +1,53 @@
-import type { OpenNativeWatch } from "./host.js";
+import { EventEmitter } from "node:events";
+import type { NativeWatchEvidence, NativeWatchHandle, OpenNativeWatch } from "./host.js";
+/** One native event: real path, FSEvents flags, event ID, and the file ID of
+ * the object the path held, or null when FSEvents recorded none. */
+export type FsEvent = readonly [path: string, flags: number, id: bigint, file: bigint | null];
+/** Amalgm's own FSEvents binding (native/fsevents/stream.c): one stream per
+ * start(), each native callback delivered to its handler as one batch, in
+ * native order. stop() returns once no callback is in flight. */
+export interface FsEventsBinding {
+    start(path: string, since: bigint | undefined, latencySeconds: number, createFlags: number, handler: (events: readonly FsEvent[]) => void): object;
+    stop(handle: object): void;
+    readonly constants: Readonly<Record<string, number>>;
+    readonly createFlags: Readonly<Record<string, number>>;
+}
+/** How long FSEvents may gather events after the first before delivering. No
+ * Defer delivers the first event after quiet at once; this only bounds how
+ * long a burst is coalesced. macOS itself adds ~10 ms that no flag removes. */
+export declare const FSEVENTS_LATENCY_SECONDS = 0.005;
+/**
+ * One FSEvents stream per handle. Node's own `fs.watch` serves every handle in
+ * the process from a single stream that libuv recreates, resuming from the
+ * present, whenever any handle opens or closes; events inside that gap are
+ * lost for every other handle. A stream of its own starts and stops alone.
+ *
+ * FSEvents is always recursive and reports real paths. A non-recursive handle
+ * keeps the entries directly inside its directory; deeper events belong to
+ * the content handles covering them, and the directory's own metadata is not
+ * an address change. Dropped, wrapped, or root-changed streams cannot name
+ * what happened and widen to the complete directory. Hard-link flags only
+ * say the named path may share its content with another name; they travel
+ * as a hint on that path, with the file ID of the object it held, and Detect
+ * decides what the alias requires.
+ */
+export declare class FsEventsWatch extends EventEmitter implements NativeWatchHandle {
+    private readonly directory;
+    private readonly prefix;
+    private readonly recursive;
+    private readonly listener;
+    private readonly native;
+    private readonly handle;
+    private readonly widening;
+    private readonly coalesced;
+    private readonly renaming;
+    private readonly aliases;
+    private readonly streamId;
+    private closed;
+    private stopping;
+    constructor(directory: string, recursive: boolean, listener: (event: string, filename: string | null, evidence: NativeWatchEvidence) => void, native?: FsEventsBinding);
+    on(event: "error" | "close", listener: (...args: any[]) => void): this;
+    close(): Promise<void>;
+    private deliver;
+}
 export declare const openFsEvents: OpenNativeWatch;

package/dist/watching/fsevents.js

@@ -1,17 +1,22 @@
 import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { createRequire } from "node:module";
-import { isAbsolute, relative, sep } from "node:path";
+import { isAbsolute, sep } from "node:path";
+/** How long FSEvents may gather events after the first before delivering. No
+ * Defer delivers the first event after quiet at once; this only bounds how
+ * long a burst is coalesced. macOS itself adds ~10 ms that no flag removes. */
+export const FSEVENTS_LATENCY_SECONDS = 0.005;
 let binding = null;
 function loadBinding() {
     if (binding)
         return binding;
     try {
-        binding = createRequire(import.meta.url)("fsevents");
+        binding = createRequire(import.meta.url)("../native/fsevents-stream.node");
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
-        throw new Error(`Watch on macOS needs the fsevents binding: ${reason}`);
+        throw new Error(`Watch on macOS needs Amalgm's FSEvents binding: ${reason}`);
     }
     return binding;
 }
@@ -25,33 +30,49 @@ function loadBinding() {
  * keeps the entries directly inside its directory; deeper events belong to
  * the content handles covering them, and the directory's own metadata is not
  * an address change. Dropped, wrapped, or root-changed streams cannot name
- * what happened and widen to the complete directory.
+ * what happened and widen to the complete directory. Hard-link flags only
+ * say the named path may share its content with another name; they travel
+ * as a hint on that path, with the file ID of the object it held, and Detect
+ * decides what the alias requires.
  */
-class FsEventsWatch extends EventEmitter {
+export class FsEventsWatch extends EventEmitter {
     directory;
+    prefix;
     recursive;
     listener;
-    stop;
+    native;
+    handle;
     widening;
+    coalesced;
     renaming;
+    aliases;
+    streamId = randomUUID();
     closed = false;
     stopping = null;
-    constructor(directory, recursive, listener) {
+    constructor(directory, recursive, listener, native = loadBinding()) {
         super();
-        const { watch, constants } = loadBinding();
-        const flag = (name) => {
-            const value = constants[name];
+        const { constants, createFlags } = native;
+        const named = (table, name) => {
+            const value = table[name];
             if (value === undefined)
-                throw new Error(`fsevents binding lacks flag ${name}`);
+                throw new Error(`FSEvents binding lacks flag ${name}`);
             return value;
         };
+        const flag = (name) => named(constants, name);
         this.directory = realpathSync(directory);
+        this.prefix = this.directory.endsWith(sep) ? this.directory : this.directory + sep;
         this.recursive = recursive;
         this.listener = listener;
-        this.widening = flag("MustScanSubDirs") | flag("UserDropped") | flag("KernelDropped")
+        this.widening = flag("UserDropped") | flag("KernelDropped")
             | flag("EventIdsWrapped") | flag("RootChanged") | flag("Mount") | flag("Unmount");
+        this.coalesced = flag("MustScanSubDirs");
         this.renaming = flag("ItemCreated") | flag("ItemRemoved") | flag("ItemRenamed");
-        this.stop = watch(this.directory, (path, flags) => this.deliver(path, flags));
+        this.aliases = flag("ItemIsHardlink") | flag("ItemIsLastHardlink");
+        this.native = native;
+        // File events name each path; WatchRoot reports the root's own address
+        // changing; NoDefer delivers the first event after quiet at once.
+        this.handle = native.start(this.directory, undefined, FSEVENTS_LATENCY_SECONDS, named(createFlags, "FileEvents") | named(createFlags, "WatchRoot") | named(createFlags, "NoDefer"), events => { for (const [path, flags, id, file] of events)
+            this.deliver(path, flags, id, file); });
     }
     on(event, listener) {
         return super.on(event, listener);
@@ -60,32 +81,46 @@ class FsEventsWatch extends EventEmitter {
         if (this.stopping)
             return this.stopping;
         this.closed = true;
-        this.stopping = this.stop().then(() => {
-            this.emit("close");
-        });
+        this.native.stop(this.handle);
+        this.stopping = Promise.resolve().then(() => { this.emit("close"); });
         return this.stopping;
     }
-    deliver(path, flags) {
+    deliver(path, flags, eventId, file) {
         if (this.closed)
             return;
         const event = (flags & this.renaming) !== 0 ? "rename" : "change";
-        if ((flags & this.widening) !== 0) {
-            this.listener(event, null);
+        const evidence = Object.freeze({
+            backend: "fsevents", streamId: this.streamId, path, flags, eventId: String(eventId),
+            scope: (flags & (this.widening | this.coalesced)) !== 0 ? "domain" : "path",
+            alias: (flags & this.aliases) !== 0, file: file === null ? null : String(file),
+        });
+        if ((flags & this.widening) !== 0 || !isAbsolute(path)) {
+            // An absent or undecodable native path loses attribution; it is not
+            // an ordinary nameless notification within a known root.
+            this.listener(event, null, Object.freeze({ ...evidence, scope: "domain" }));
             return;
         }
-        const local = relative(this.directory, path);
-        if (local === ".." || local.startsWith(`..${sep}`) || isAbsolute(local)) {
-            this.listener(event, null);
+        // Both are physical canonical paths: containment is one prefix test. A
+        // path that is not canonical fails it and widens to the domain.
+        const local = path === this.directory ? ""
+            : path.startsWith(this.prefix) ? path.slice(this.prefix.length) : null;
+        if (local === null) {
+            this.listener(event, null, Object.freeze({ ...evidence, scope: "domain" }));
             return;
         }
         if (local === "") {
-            if (this.recursive)
-                this.listener(event, null);
+            if (this.recursive || (flags & this.coalesced) !== 0)
+                this.listener(event, null, evidence);
             return;
         }
         if (!this.recursive && local.includes(sep))
             return;
-        this.listener(event, local);
+        // The native stream is recursive even for a logical address handle.
+        // Preserve that handle's declared coverage before interpreting an entry;
+        // incidental deep activity outside it is not a new watched namespace.
+        // MustScanSubDirs describes that reported subtree, unlike stream loss;
+        // an entirely disjoint subtree does not erase this handle's coverage.
+        this.listener(event, local, evidence);
     }
 }
 export const openFsEvents = (directory, options, listener) => new FsEventsWatch(directory, options.recursive, listener);

package/dist/watching/fsevents.js.map

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

package/dist/watching/host.d.ts

@@ -1,4 +1,4 @@
-import { type SuspicionSnapshot } from "@amalgm/live";
+import { type SuspicionPending, type SuspicionSnapshot } from "@amalgm/live";
 export interface WatchGround {
     readonly rootId: string;
     readonly directory: string;
@@ -14,10 +14,35 @@ export interface WatchHealth {
     readonly addressHandles: number;
     readonly reason?: string;
 }
+/** One root's live cut. Its owner settles what it proved and always
+ * releases it; a released cut can no longer be settled or waited on. */
 export interface WatchObservation {
     readonly rootId: string;
     readonly directory: string;
     readonly suspicion: SuspicionSnapshot;
+    /** These roots must complete together; native event IDs never settle them. */
+    readonly domain?: WatchDomainCutoff;
+}
+/** What one root still owes, for scheduling only. It proves nothing. */
+export interface WatchPending {
+    readonly rootId: string;
+    readonly directory: string;
+    readonly pending: SuspicionPending;
+}
+/** The binding world one turn began in. */
+export interface WatchBoundary {
+    readonly owner: string;
+    readonly bindings: number;
+}
+interface WatchDomainCutoff {
+    readonly owner: string;
+    readonly generation: number;
+    readonly bindings: number;
+    readonly participants: readonly {
+        readonly rootId: string;
+        readonly directory: string;
+        readonly generation: number;
+    }[];
 }
 export interface WatchCoverageEvidence {
     readonly health: WatchHealth;
@@ -42,9 +67,25 @@ export interface NativeWatchHandle {
     close(): void | Promise<void>;
     on(event: "error" | "close", listener: (...args: any[]) => void): this;
 }
+export interface NativeWatchEvidence {
+    readonly backend: "fsevents";
+    readonly streamId: string;
+    readonly path: string;
+    readonly flags: number;
+    /** FSEvents IDs are uint64; decimal text keeps every one exact. */
+    readonly eventId: string;
+    readonly scope: "path" | "domain";
+    /** The named path may be one of several links to the same content. A hint
+     * for Detect on that path, never a wider Watch scope. */
+    readonly alias: boolean;
+    /** The FSEvents file ID, in decimal: the object the path held within its
+     * filesystem. null when the event recorded none. */
+    readonly file: string | null;
+}
+type NativeWatchListener = (event: string, filename: string | Buffer | null, evidence?: NativeWatchEvidence) => void;
 export type OpenNativeWatch = (directory: string, options: {
     readonly recursive: boolean;
-}, listener: (event: string, filename: string | Buffer | null) => void) => NativeWatchHandle;
+}, listener: NativeWatchListener) => NativeWatchHandle;
 export interface NodeWatchHostOptions {
     readonly open?: OpenNativeWatch;
     /** Injectable only for deterministic physical-backend certification. */
@@ -61,6 +102,8 @@ export interface WatchEventEvidence {
     readonly directory: string;
     readonly path: string | null;
     readonly at: number;
+    readonly event: string;
+    readonly native?: NativeWatchEvidence;
 }
 export interface WatchCloseOptions {
     /** A one-shot effect that introduced no user edits may close without a catch-up scan. */
@@ -90,9 +133,22 @@ export declare class NodeWatchHost {
     private readonly stopErrors;
     private closeTask;
     private plan;
+    private readonly domainOwner;
+    private bindingGeneration;
+    private domainGeneration;
+    private resolvedDomainGeneration;
+    private coverageGap;
     private retryTimer;
     private retryAttempt;
     private closed;
+    private finalCutoff;
+    /** Native notices beyond this turn's slice, in arrival order. */
+    private backlog;
+    private backlogHead;
+    private sliceLeft;
+    /** When this turn's budget ends; set by the turn's first admission. */
+    private sliceEnds;
+    private turnScheduled;
     private currentHealth;
     constructor(options: NodeWatchHostOptions);
     reconcile(grounds: readonly WatchGround[], options?: WatchReconcileOptions): WatchHealth;
@@ -102,12 +158,68 @@ export declare class NodeWatchHost {
     /** Exact physical/logical coverage evidence for diagnostics and product
      * readiness. This observes the one host; it never creates a handle. */
     evidence(): WatchCoverageEvidence;
-    observations(): readonly WatchObservation[];
+    /** What every root still owes. Scheduling reads this; only a cut proves. */
+    pending(): readonly WatchPending[];
+    /** Cut every root at what it owes now; an owed domain cuts all roots
+     * together. Native cutoffs are never widened by the passage of time. */
+    freeze(): readonly WatchObservation[];
+    /** Cut the selected roots alone. A partial cut never carries the domain.
+     * "escalated" cuts the rings a named proof escalated while no ring owes
+     * the complete root; otherwise the complete root. */
+    freezeRoots(select: (root: {
+        readonly rootId: string;
+        readonly directory: string;
+    }) => boolean, scope: "owed" | "complete" | "escalated"): readonly WatchObservation[];
+    /** Cut one root at exactly these named rings. A lane that proves part of a
+     * root's names cuts only its own; the rest stay owed to their lane. */
+    freezePaths(rootId: string, paths: readonly string[]): WatchObservation | null;
+    /** A ticket for exact addresses: each root waits only for the named
+     * addresses inside it. A root inside an address, or an address outside
+     * every root, needs that complete proof — the scope `suspect` rang. */
+    freezeAddresses(absolutePaths: readonly string[]): readonly WatchObservation[];
+    private cut;
+    /** Every participant is one root's complete cut. */
+    private domainObservations;
+    /** One finite complete-lane batch: an owed domain, else the roots owing a
+     * complete-root or escalated proof. Named rings are not complete work;
+     * their own lanes serve them. A root whose ground is `held` is not cut: it
+     * is `withheld`. A `parked` root is not cut either; its park's own cause
+     * wakes it. A domain, which cuts every root together, waits whole. */
+    selectComplete(held: (directory: string) => boolean, parked: (rootId: string) => boolean): {
+        readonly cuts: readonly WatchObservation[];
+        readonly withheld: readonly string[];
+    };
+    /** The binding world a turn begins in; a later rebinding invalidates it. */
+    boundary(): WatchBoundary;
+    boundaryCurrent(boundary: WatchBoundary): boolean;
+    /** A named cut widened: its rings keep their generations and are now owed
+     * a complete-root proof. The cut itself stays live until released. */
+    escalate(observation: WatchObservation): void;
+    /** Names another examiner found (the sweep) that a named proof could not
+     * settle. Watch never rang them, so they are rung here and escalated at
+     * once: owed the same scoped wider proof as a widened native ring, never
+     * the complete root merely because Watch did not hear them. */
+    escalatePaths(rootId: string, paths: readonly string[]): void;
+    /** Every cut must be released by its owner, proved or not. */
+    release(observations: readonly WatchObservation[]): void;
+    private completeDomain;
     settle(observations: readonly WatchObservation[]): void;
-    /** True only when every generation frozen by this observation has been
-     * proved. Newer rings do not change the answer and retain their own pass. */
+    /** True only when everything each cut scoped at or before its generation
+     * has been proved, by any proof. Newer rings keep their own pass. A root
+     * no longer bound owes this caller nothing. */
     settled(observations: readonly WatchObservation[]): boolean;
+    /** A capture may depend on another root's unfinished observation. Return
+     * scopes only; Apply ownership and recovery decisions remain with the host. */
+    dependencies(observations: readonly WatchObservation[]): readonly string[];
+    /** Coverage is continuous while healthy. A catch-up close is a final cutoff,
+     * not a gap: it suspects every root before retiring its handles, and every
+     * later change belongs to the next startup's blind interval. */
+    continuous(): boolean;
+    bindingsCurrent(observations: readonly WatchObservation[]): boolean;
     suspectAll(): void;
+    /** One ambiguous effect can reach another root through a historical alias.
+     * Keep one bounded obligation, not a history of native notifications. */
+    suspectDomain(): void;
     /** A host effect that touched exact ground rings the same named suspicion a
      * native callback would: each root containing the address suspects that
      * one path. An address outside every root suspects the complete plan, so an
@@ -128,9 +240,21 @@ export declare class NodeWatchHost {
      * in question; those roots are returned. */
     private rearmAddressedContent;
     private suspectRoots;
+    /** Every doorbell enters here; null suspects the complete root. A ring can
+     * only start an obligation, so examiners hear it only when none was owed. */
+    private ring;
+    private observeObligation;
+    private loseCoverage;
     private degrade;
     private publishHealth;
     private signal;
+    /** Admit a notice now while this turn's slice lasts and nothing earlier
+     * waits; otherwise after every earlier notice, in a later turn. */
+    private admit;
+    private admitNow;
+    /** Each turn renews the slice and admits the oldest waiting notices. */
+    private nextTurn;
     private scheduleRetry;
     private cancelRetry;
 }
+export {};