@amalgm/live 0.2.18 → 0.2.20

package/PURPOSE.md

@@ -20,8 +20,9 @@ its cutover.
 
 1. **The SDK owns portable live contracts, not a machine.** Entity-record
    shapes, resource identifiers, content manifests, checksums, frame shapes,
-   mutation envelopes, and ordering rules belong here; paths, inodes,
-   watchers, services, and local database files do not.
+   mutation envelopes, ordering rules, and portable Watch laws belong here;
+   paths, inodes, OS watcher handles, services, and local database files do
+   not.
 2. **A host supplies its own effects.** The SDK receives transport, durable
    journal, content-store, clock, and cryptography adapters. It never reaches
    into Node globals, user homes, or a product-specific HTTP server to find
@@ -89,17 +90,21 @@ its cutover.
     the same authenticated private registry. A reference in the core graph
     points to the external root UUID.
 20. **Materialization is local and selective.** Login installs the core graph;
-    `files add <workspace>` installs one owned workspace root. The local SQLite
-    table contains rows only for roots materialized on that machine, while
-    cloud reconciliation preserves every unmaterialized root.
-21. **A Git marker classifies its containing directory.** An externally
-    registered root with valid `.git` evidence is `repo.git`, as is any nested
-    directory with that evidence; the UUID does not change when the type does.
-    `.git` itself is repository transport metadata and never receives an
-    entity row. Worktree children retain local UUID rows, while their
-    identities ride in the repository state manifest rather than becoming
-    individual cloud records. A shallow repository carries its declared Git
-    history boundary, so a new machine never invents history beyond it.
+    `files add <workspace>` installs one owned workspace root and the exact
+    portable reference entity that names it. The local SQLite table contains
+    rows only for roots materialized on that machine, while cloud reconciliation
+    preserves every unmaterialized root. A newly installed and verified graph
+    is the initial Watch baseline for that root; opening coverage must not
+    reinterpret the downloader's own writes as user edits.
+21. **A Git marker classifies its containing directory.** The presence of a
+    `.git` directory or file makes its containing directory `repo.git`; its
+    removal returns that same UUID to `workspace` or `folder`. Git command
+    availability governs Card + Checkpoint capture, never classification, and
+    `.git` itself is repository transport metadata that receives no entity
+    row. Worktree children retain local UUID rows, while their identities ride
+    in the repository state manifest rather than becoming individual cloud
+    records. A shallow repository carries its declared Git history boundary,
+    so a new machine never invents history beyond it.
 22. **Transfer moves content; it never discovers state.** `upload` moves one
     already-registered immutable artifact toward cloud storage and `download`
     moves that same artifact toward a machine cache. Neither operation scans,
@@ -185,10 +190,11 @@ src/machines/    transport-neutral state machines: sequence ordering + gap
 src/entities/    the entity model's rule surface: the six-field record,
                  derived versions, lifecycle laws, move planning, the
                  cloud and repo-state codecs — behind injected ports.
-src/detection/   the Detect/Watch pure cores: the adapter contract, the
-                 three-channel compare (diff) core, coverage, continuity
-                 verdicts, suspicion scope, classification, refusals,
-                 enrollment policy.
+src/watching/    the Watch pure cores: minimal coverage ownership and
+                 generation-safe suspicion.
+src/detection/   the Detect pure cores: the adapter contract, three-channel
+                 compare (diff), continuity verdicts, classification,
+                 refusals, and enrollment policy.
 src/registration/ the login-time user-ground convergence operation and its
                   injected local/cloud effect ports.
 src/transfer/    type-aware immutable artifact upload/download operations;

package/README.md

@@ -23,6 +23,7 @@ normative specifications live in [docs/](docs/):
 | [shared-realtime-wave-3.md](docs/shared-realtime-wave-3.md) | the multi-user cloud-authority design |
 | [extraction-boundary.md](docs/extraction-boundary.md) | what moves here from the engine runtime, and in what order |
 | [user-ground-login.md](docs/user-ground-login.md) | first-login publication, later-device materialization, and Watch readiness |
+| [watching.md](docs/watching.md) | Watch purpose, axioms, lifecycle matrix, and cross-platform test layers |
 
 ## Surfaces
 

package/dist/detection/classify.d.ts

@@ -30,9 +30,9 @@ export interface ClassifyEvidence {
     readonly binary: boolean;
 }
 export declare function classifyFile({ binary }: ClassifyEvidence): FileType;
-/** Git truth belongs to the directory that contains it. The host proves the
- * marker (including linked-worktree `.git` files); this pure policy names the
- * entity type and never opens a path or invokes Git itself. */
+/** Git truth belongs to the directory that contains its marker. The host
+ * reports marker presence (including linked-worktree `.git` files); Git
+ * command health is transfer evidence, never classification evidence. */
 export interface RepositoryEvidence {
     readonly repository: boolean;
 }
@@ -41,7 +41,7 @@ export declare function classifyDirectory({ repository }: RepositoryEvidence): D
  * root wears `repo.git`; an ordinary root wears `workspace`. */
 export declare function classifyRegisteredRoot({ repository }: RepositoryEvidence): RegisteredRootType;
 /** `.git` is cargo of a repository entity, never one of its worktree
- * children. A stale or invalid marker under ordinary folder ground is not
- * hidden by this rule; the host's repository evidence decides the boundary. */
+ * children. Marker presence makes the parent a repository before this rule is
+ * asked, regardless of whether Git can currently consume that marker. */
 export declare function isRepositoryMetadataEntry(parentType: DirectoryType | RegisteredRootType, name: string): boolean;
 //# sourceMappingURL=classify.d.ts.map

package/dist/detection/classify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../src/detection/classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,WAAW,CAAC;AACnD,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,CAAC;AAClD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,UAAU,CAAC;AAE1D,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,EAAE,gBAAgB,GAAG,QAAQ,CAEnE;AAED;;+DAE+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAgB,iBAAiB,CAAC,EAAE,UAAU,EAAE,EAAE,kBAAkB,GAAG,aAAa,CAEnF;AAED;gEACgE;AAChE,wBAAgB,sBAAsB,CAAC,EAAE,UAAU,EAAE,EAAE,kBAAkB,GAAG,kBAAkB,CAE7F;AAED;;+EAE+E;AAC/E,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,aAAa,GAAG,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/G"}
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../src/detection/classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,WAAW,CAAC;AACnD,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,CAAC;AAClD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,UAAU,CAAC;AAE1D,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,EAAE,gBAAgB,GAAG,QAAQ,CAEnE;AAED;;yEAEyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAgB,iBAAiB,CAAC,EAAE,UAAU,EAAE,EAAE,kBAAkB,GAAG,aAAa,CAEnF;AAED;gEACgE;AAChE,wBAAgB,sBAAsB,CAAC,EAAE,UAAU,EAAE,EAAE,kBAAkB,GAAG,kBAAkB,CAE7F;AAED;;yEAEyE;AACzE,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,aAAa,GAAG,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/G"}

package/dist/detection/classify.js

@@ -34,8 +34,8 @@ export function classifyRegisteredRoot({ repository }) {
     return repository ? 'repo.git' : 'workspace';
 }
 /** `.git` is cargo of a repository entity, never one of its worktree
- * children. A stale or invalid marker under ordinary folder ground is not
- * hidden by this rule; the host's repository evidence decides the boundary. */
+ * children. Marker presence makes the parent a repository before this rule is
+ * asked, regardless of whether Git can currently consume that marker. */
 export function isRepositoryMetadataEntry(parentType, name) {
     return parentType === 'repo.git' && name === '.git';
 }

package/dist/detection/classify.js.map

@@ -1 +1 @@
-{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../src/detection/classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAWH,MAAM,UAAU,YAAY,CAAC,EAAE,MAAM,EAAoB;IACvD,OAAO,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC;AAC9C,CAAC;AASD,MAAM,UAAU,iBAAiB,CAAC,EAAE,UAAU,EAAsB;IAClE,OAAO,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC5C,CAAC;AAED;gEACgE;AAChE,MAAM,UAAU,sBAAsB,CAAC,EAAE,UAAU,EAAsB;IACvE,OAAO,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;AAC/C,CAAC;AAED;;+EAE+E;AAC/E,MAAM,UAAU,yBAAyB,CAAC,UAA8C,EAAE,IAAY;IACpG,OAAO,UAAU,KAAK,UAAU,IAAI,IAAI,KAAK,MAAM,CAAC;AACtD,CAAC"}
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../src/detection/classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAWH,MAAM,UAAU,YAAY,CAAC,EAAE,MAAM,EAAoB;IACvD,OAAO,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC;AAC9C,CAAC;AASD,MAAM,UAAU,iBAAiB,CAAC,EAAE,UAAU,EAAsB;IAClE,OAAO,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC5C,CAAC;AAED;gEACgE;AAChE,MAAM,UAAU,sBAAsB,CAAC,EAAE,UAAU,EAAsB;IACvE,OAAO,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;AAC/C,CAAC;AAED;;yEAEyE;AACzE,MAAM,UAAU,yBAAyB,CAAC,UAA8C,EAAE,IAAY;IACpG,OAAO,UAAU,KAAK,UAAU,IAAI,IAAI,KAAK,MAAM,CAAC;AACtD,CAAC"}

package/dist/detection/continuity.d.ts

@@ -13,7 +13,7 @@
  * wiring, because they re-aim watchers and scans.
  */
 import type { PhysicalIdentity } from './diff.js';
-import type { RootKind } from './coverage.js';
+import type { RootKind } from '../watching/coverage.js';
 /** What one look at an address found standing there. */
 export type GroundKind = 'file' | 'dir' | 'link' | 'other';
 export interface GroundStat extends PhysicalIdentity {

package/dist/detection/continuity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"continuity.d.ts","sourceRoot":"","sources":["../../src/detection/continuity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,UAAW,SAAQ,gBAAgB;IAClD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,CAAC;IACrD;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,gBAAgB,GAAG,IAAI,CAAC;CACvE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,gBAAgB,GAAG,IAAI,CAAC;IACzE,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,cAAc,EAAE,KAAK,cAAc,GAAG,IAAI,CAAC;IACtG,QAAQ,CAAC,gBAAgB,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC;CAC9D;AAED,wBAAgB,gBAAgB,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,eAAe,GAAG,kBAAkB,CAmEjG"}
+{"version":3,"file":"continuity.d.ts","sourceRoot":"","sources":["../../src/detection/continuity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,UAAW,SAAQ,gBAAgB;IAClD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,CAAC;IACrD;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,gBAAgB,GAAG,IAAI,CAAC;CACvE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,gBAAgB,GAAG,IAAI,CAAC;IACzE,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,cAAc,EAAE,KAAK,cAAc,GAAG,IAAI,CAAC;IACtG,QAAQ,CAAC,gBAAgB,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC;CAC9D;AAED,wBAAgB,gBAAgB,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,eAAe,GAAG,kBAAkB,CAmEjG"}

package/dist/detection/index.d.ts

@@ -1,6 +1,6 @@
 /**
- * Detection — the pure cores of the Watch/Detect rails, ported from the
- * engine's observer and registration boundary. Normative sources:
+ * Detection — the pure cores that turn observed disk evidence into facts.
+ * Normative sources:
  * entity-model.md (identity axioms, the two continuity witnesses) and
  * entity-implementation.md (the ratified seams).
  *
@@ -16,15 +16,12 @@
  * - `refusal`           declined-vs-broken, named where it is raised
  * - `enrollment`        the default manual enrollment policy
  * - `diff`              the compare functions: file/dir/link identity
- * - `coverage`          one OS watcher per outermost tree
  * - `continuity`        root rescue and the undecided address
  */
 export * from './adapter-contract.js';
 export * from './classify.js';
 export * from './continuity.js';
-export * from './coverage.js';
 export * from './diff.js';
 export * from './enrollment.js';
 export * from './refusal.js';
-export * from './suspicion.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/detection/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/detection/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/detection/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}

package/dist/detection/index.js

@@ -1,6 +1,6 @@
 /**
- * Detection — the pure cores of the Watch/Detect rails, ported from the
- * engine's observer and registration boundary. Normative sources:
+ * Detection — the pure cores that turn observed disk evidence into facts.
+ * Normative sources:
  * entity-model.md (identity axioms, the two continuity witnesses) and
  * entity-implementation.md (the ratified seams).
  *
@@ -16,15 +16,12 @@
  * - `refusal`           declined-vs-broken, named where it is raised
  * - `enrollment`        the default manual enrollment policy
  * - `diff`              the compare functions: file/dir/link identity
- * - `coverage`          one OS watcher per outermost tree
  * - `continuity`        root rescue and the undecided address
  */
 export * from './adapter-contract.js';
 export * from './classify.js';
 export * from './continuity.js';
-export * from './coverage.js';
 export * from './diff.js';
 export * from './enrollment.js';
 export * from './refusal.js';
-export * from './suspicion.js';
 //# sourceMappingURL=index.js.map

package/dist/detection/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/detection/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/detection/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}

package/dist/files/commands.d.ts

@@ -41,6 +41,7 @@ export interface FilesAddPorts {
     lookupRegistry(): Promise<CloudUserGround>;
     materializeWorkspace(input: {
         readonly workspace: CloudEntityRecord;
+        readonly reference: CloudEntityRecord;
         readonly records: readonly CloudEntityRecord[];
         readonly destinationParent: string;
         readonly cloudHead: string;
@@ -48,9 +49,15 @@ export interface FilesAddPorts {
         readonly path: string;
         readonly rows: number;
         readonly records: readonly CloudEntityRecord[];
+        readonly reference: CloudEntityRecord;
         readonly alreadyMaterialized: boolean;
     }>;
-    coverWorkspace(workspaceId: string): Promise<{
+    coverWorkspace(input: {
+        readonly workspaceId: string;
+        /** The host may adopt this exact graph as Watch's initial baseline only
+         * when this add invocation just materialized and verified it. */
+        readonly baseline: 'authoritative-install' | 'existing';
+    }): Promise<{
         readonly active: boolean;
         readonly roots: number;
     }>;
@@ -68,6 +75,7 @@ export interface FilesAddResult {
 /** Select exactly one root graph. Sibling roots are intentionally absent. */
 export declare function workspaceGraph(records: readonly CloudEntityRecord[], workspaceId: string): {
     readonly workspace: CloudEntityRecord;
+    readonly reference: CloudEntityRecord;
     readonly records: readonly CloudEntityRecord[];
 };
 /** Materialize one owned workspace root and establish Watch coverage for it. */

package/dist/files/commands.d.ts.map

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

package/dist/files/commands.js

@@ -50,6 +50,11 @@ export function workspaceGraph(records, workspaceId) {
     if (workspace.parentUUID !== null || !['workspace', 'repo.git'].includes(workspace.type)) {
         throw new Error(`entity ${normalizedId} is not a workspace root`);
     }
+    const references = snapshot.records.filter((record) => record.status === 'active'
+        && record.type === 'reference' && record.payloadVersion === normalizedId);
+    if (references.length !== 1) {
+        throw new Error(`workspace ${normalizedId} must have exactly one durable reference`);
+    }
     const included = new Set([normalizedId]);
     let changed = true;
     while (changed) {
@@ -63,6 +68,7 @@ export function workspaceGraph(records, workspaceId) {
     }
     return {
         workspace,
+        reference: references[0],
         records: snapshot.records.filter((record) => included.has(record.uuid)),
     };
 }
@@ -80,10 +86,14 @@ export async function addFilesWorkspace(workspaceId, destinationParent, ports) {
     const installedRecords = snapshotFromRecords(installed.records || []).records;
     if (!Number.isSafeInteger(installed.rows)
         || installed.rows !== installedRecords.length
-        || !sameRecords(travelingRecords(installedRecords), selected.records)) {
+        || !sameRecords(travelingRecords(installedRecords), selected.records)
+        || !sameRecords([installed.reference], [selected.reference])) {
         throw new Error('workspace materialization did not persist exactly the selected graph');
     }
-    const coverage = await ports.coverWorkspace(normalizedId);
+    const coverage = await ports.coverWorkspace({
+        workspaceId: normalizedId,
+        baseline: installed.alreadyMaterialized === true ? 'existing' : 'authoritative-install',
+    });
     if (coverage.active !== true || !Number.isSafeInteger(coverage.roots) || coverage.roots < 1) {
         throw new Error('workspace watcher coverage is not active');
     }

package/dist/files/commands.js.map

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

package/dist/index.d.ts

@@ -12,6 +12,7 @@
 export * from './contracts/index.js';
 export * from './machines/index.js';
 export * from './entities/index.js';
+export * from './watching/index.js';
 export * from './detection/index.js';
 export * from './registration/index.js';
 export * from './files/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -12,6 +12,7 @@
 export * from './contracts/index.js';
 export * from './machines/index.js';
 export * from './entities/index.js';
+export * from './watching/index.js';
 export * from './detection/index.js';
 export * from './registration/index.js';
 export * from './files/index.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC"}

package/dist/watching/coverage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The coverage law: one OS watcher per outermost tree.
+ *
+ * A recursive watcher on a directory hears events beneath it at every depth,
+ * so a root enclosed by watched ground already has content coverage. Opening
+ * another recursive watcher over enclosed ground adds no information and, on
+ * Linux, pays for the same inotify ground again.
+ *
+ * These are pure decisions over canonical root paths. The host owns opening,
+ * sharing, and closing physical handles.
+ */
+/** The three root kinds; only a single file moves its doorbell to its parent. */
+export type RootKind = 'file' | 'files' | 'repo';
+export interface WatchRoot {
+    readonly rootId: string;
+    /** Canonical absolute path using `/` separators and no trailing separator. */
+    readonly path: string;
+    readonly kind: RootKind;
+}
+/**
+ * Directory roots guard themselves. A single-file root rings through its
+ * parent because watching a file inode goes deaf when an atomic save replaces
+ * that inode.
+ */
+export declare function doorbellGround(root: WatchRoot): string;
+/**
+ * Return the outermost directory root whose recursive handle covers `root`,
+ * or null when `root` owns its physical coverage.
+ */
+export declare function watchOwnerOf(root: WatchRoot, roots: readonly WatchRoot[]): WatchRoot | null;
+/** Every logical root routed through an owner's physical handle. */
+export declare function coveredRoots(owner: WatchRoot, roots: readonly WatchRoot[]): WatchRoot[];
+//# sourceMappingURL=coverage.d.ts.map

package/dist/watching/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/watching/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,iFAAiF;AACjF,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AASD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,CAS3F;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,EAAE,CAGvF"}

package/dist/watching/coverage.js

@@ -0,0 +1,49 @@
+/**
+ * The coverage law: one OS watcher per outermost tree.
+ *
+ * A recursive watcher on a directory hears events beneath it at every depth,
+ * so a root enclosed by watched ground already has content coverage. Opening
+ * another recursive watcher over enclosed ground adds no information and, on
+ * Linux, pays for the same inotify ground again.
+ *
+ * These are pure decisions over canonical root paths. The host owns opening,
+ * sharing, and closing physical handles.
+ */
+/** '/a/b' → '/a'; '/a' → '/'; a bare name → '.'. */
+const parentDirOf = (path) => {
+    const cut = path.lastIndexOf('/');
+    if (cut < 0)
+        return '.';
+    return cut === 0 ? '/' : path.slice(0, cut);
+};
+/**
+ * Directory roots guard themselves. A single-file root rings through its
+ * parent because watching a file inode goes deaf when an atomic save replaces
+ * that inode.
+ */
+export function doorbellGround(root) {
+    return root.kind === 'file' ? parentDirOf(root.path) : root.path;
+}
+/**
+ * Return the outermost directory root whose recursive handle covers `root`,
+ * or null when `root` owns its physical coverage.
+ */
+export function watchOwnerOf(root, roots) {
+    const ground = doorbellGround(root);
+    let owner = null;
+    for (const other of roots) {
+        if (other.rootId === root.rootId || other.kind === 'file')
+            continue;
+        if (ground !== other.path && !ground.startsWith(`${other.path}/`))
+            continue;
+        if (!owner || other.path.length < owner.path.length)
+            owner = other;
+    }
+    return owner;
+}
+/** Every logical root routed through an owner's physical handle. */
+export function coveredRoots(owner, roots) {
+    return roots.filter((root) => root.rootId !== owner.rootId
+        && watchOwnerOf(root, roots)?.rootId === owner.rootId);
+}
+//# sourceMappingURL=coverage.js.map

package/dist/watching/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/watching/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,oDAAoD;AACpD,MAAM,WAAW,GAAG,CAAC,IAAY,EAAU,EAAE;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACxB,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC9C,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAe;IAC5C,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAe,EAAE,KAA2B;IACvE,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,KAAK,GAAqB,IAAI,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QACpE,IAAI,MAAM,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC;YAAE,SAAS;QAC5E,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM;YAAE,KAAK,GAAG,KAAK,CAAC;IACrE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,KAAgB,EAAE,KAA2B;IACxE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;WACrD,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC,CAAC;AAC3D,CAAC"}

package/dist/watching/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Watching — portable laws for minimal filesystem notification coverage and
+ * durable suspicion. OS handles belong to the host; Detect begins only after
+ * these modules have said where disk truth must be reread.
+ */
+export * from './coverage.js';
+export * from './suspicion.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/watching/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watching/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}

package/dist/watching/index.js

@@ -0,0 +1,8 @@
+/**
+ * Watching — portable laws for minimal filesystem notification coverage and
+ * durable suspicion. OS handles belong to the host; Detect begins only after
+ * these modules have said where disk truth must be reread.
+ */
+export * from './coverage.js';
+export * from './suspicion.js';
+//# sourceMappingURL=index.js.map

package/dist/watching/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watching/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}

package/dist/{detection → watching}/suspicion.d.ts

@@ -1,21 +1,19 @@
 /**
- * The portable Watch suspicion scope.
- *
- * A filesystem event is only a doorbell: its path says where truth must be
- * reread, never what happened there. Named suspicion stays live until one
- * settled observation proves it. Generation stamps prevent an observation
+ * A filesystem notification is only a doorbell: its path says where truth
+ * must be reread, never what happened there. Named suspicion stays live until
+ * one settled observation proves it. Generation stamps prevent an observation
  * from consuming a second ring that arrived while it was reading.
  */
 export interface SuspicionSnapshot {
     /** The latest ring this observation is allowed to consume. */
     readonly generation: number;
-    /** null means the complete covered root; otherwise these paths and their descendants. */
+    /** null means the complete covered root; otherwise these paths and descendants. */
     readonly paths: readonly string[] | null;
 }
 export interface SuspicionScope {
     /** Add one OS path hint. null means the OS could not name a path. */
     ring(path: string | null): void;
-    /** Startup, catch-up, watcher death, and explicit flush cannot trust prior silence. */
+    /** Startup, catch-up, watcher death, and explicit flush cannot trust silence. */
     suspectAll(): void;
     /** Freeze the suspicion one observation will prove. */
     snapshot(): SuspicionSnapshot;

package/dist/watching/suspicion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suspicion.d.ts","sourceRoot":"","sources":["../../src/watching/suspicion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAChC,iFAAiF;IACjF,UAAU,IAAI,IAAI,CAAC;IACnB,uDAAuD;IACvD,QAAQ,IAAI,iBAAiB,CAAC;IAC9B,iEAAiE;IACjE,MAAM,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAQD,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,OAAO,CAGvF;AAED,wBAAgB,oBAAoB,CAAC,GAAG,SAAM,GAAG,cAAc,CAmD9D"}

package/dist/{detection → watching}/suspicion.js

@@ -1,17 +1,15 @@
 /**
- * The portable Watch suspicion scope.
- *
- * A filesystem event is only a doorbell: its path says where truth must be
- * reread, never what happened there. Named suspicion stays live until one
- * settled observation proves it. Generation stamps prevent an observation
+ * A filesystem notification is only a doorbell: its path says where truth
+ * must be reread, never what happened there. Named suspicion stays live until
+ * one settled observation proves it. Generation stamps prevent an observation
  * from consuming a second ring that arrived while it was reading.
  */
 const normalizeHint = (path) => {
-    const normalized = path.replaceAll('\\', '/').replace(/^\.\//, '').replace(/\/+$/, '');
-    if (!normalized || normalized.startsWith('/')
-        || normalized.split('/').some((segment) => segment === '..'))
+    if (!path || path.startsWith('/') || path.includes('\0'))
         return null;
-    return normalized;
+    if (path.split('/').some((segment) => !segment || segment === '.' || segment === '..'))
+        return null;
+    return path;
 };
 /** A named directory suspects every descendant. Exact files suspect themselves. */
 export function pathIsSuspect(path, suspects) {

package/dist/watching/suspicion.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/live",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Portable realtime SDK for Amalgm — wire contracts, mutation discipline, and delivery state machines behind host-injected adapters.",
   "type": "module",
   "license": "UNLICENSED",
@@ -36,6 +36,10 @@
       "types": "./dist/registration/index.d.ts",
       "default": "./dist/registration/index.js"
     },
+    "./watching": {
+      "types": "./dist/watching/index.d.ts",
+      "default": "./dist/watching/index.js"
+    },
     "./files": {
       "types": "./dist/files/index.d.ts",
       "default": "./dist/files/index.js"
@@ -53,7 +57,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
     "test": "npm run build && node --test tests/",
     "test:parity": "npm run build && node --test tests/parity/",
     "test:conformance": "npm run build && node --test tests/conformance/"

package/dist/detection/coverage.d.ts

@@ -1,43 +0,0 @@
-/**
- * The coverage law: one OS watcher per outermost tree. Ratified by
- * entity-model.md (enclosed-ground coverage) and
- * entity-implementation.md (the doorbell matrix).
- *
- * A recursive watcher on a directory hears every event beneath it, at
- * any depth — so a root enclosed by watched ground already has its
- * content observed, exactly as its ADDRESS is already observed. Opening
- * a second watcher over enclosed ground buys nothing on any platform
- * and, on Linux — where a recursive watch is silently one inotify slot
- * PER DIRECTORY against a small kernel budget — exhausts the kernel.
- * Doorbells are shared; what a root DOES with its dings (files
- * channels, repo Card+Checkpoint) stays its own type's business.
- *
- * Pure functions over root rows — no handles, no state. The host owns
- * opening and closing; this module only answers "who guards whom".
- * Addresses are absolute '/'-separated paths with no trailing
- * separator, as the enrollment boundary records them.
- */
-/** The three root kinds; only 'file' changes a doorbell's ground. */
-export type RootKind = 'file' | 'files' | 'repo';
-export interface WatchRoot {
-    readonly rootId: string;
-    readonly path: string;
-    readonly kind: RootKind;
-}
-/**
- * The ground a root's doorbell must cover: a directory root guards
- * itself; a single-file root's bell lives on its parent directory (the
- * file's own inode goes deaf on atomic saves).
- */
-export declare function doorbellGround(root: WatchRoot): string;
-/**
- * The root whose OS watcher covers `root`'s doorbell ground, or null
- * when `root` guards itself. The OUTERMOST enclosing directory root
- * wins: with A ⊃ B ⊃ C only A holds a handle, and every deeper root —
- * B, C, nested repos, single files — rides it. A file root can never
- * cover anything.
- */
-export declare function watchOwnerOf(root: WatchRoot, roots: readonly WatchRoot[]): WatchRoot | null;
-/** Every live root covered by `owner` (owner excluded). */
-export declare function coveredRoots(owner: WatchRoot, roots: readonly WatchRoot[]): WatchRoot[];
-//# sourceMappingURL=coverage.d.ts.map

package/dist/detection/coverage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/detection/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,qEAAqE;AACrE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AASD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,CAS3F;AAED,2DAA2D;AAC3D,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,EAAE,CAGvF"}

package/dist/detection/coverage.js

@@ -1,60 +0,0 @@
-/**
- * The coverage law: one OS watcher per outermost tree. Ratified by
- * entity-model.md (enclosed-ground coverage) and
- * entity-implementation.md (the doorbell matrix).
- *
- * A recursive watcher on a directory hears every event beneath it, at
- * any depth — so a root enclosed by watched ground already has its
- * content observed, exactly as its ADDRESS is already observed. Opening
- * a second watcher over enclosed ground buys nothing on any platform
- * and, on Linux — where a recursive watch is silently one inotify slot
- * PER DIRECTORY against a small kernel budget — exhausts the kernel.
- * Doorbells are shared; what a root DOES with its dings (files
- * channels, repo Card+Checkpoint) stays its own type's business.
- *
- * Pure functions over root rows — no handles, no state. The host owns
- * opening and closing; this module only answers "who guards whom".
- * Addresses are absolute '/'-separated paths with no trailing
- * separator, as the enrollment boundary records them.
- */
-/** '/a/b' → '/a'; '/a' → '/'; a bare name → '.'. */
-const parentDirOf = (path) => {
-    const cut = path.lastIndexOf('/');
-    if (cut < 0)
-        return '.';
-    return cut === 0 ? '/' : path.slice(0, cut);
-};
-/**
- * The ground a root's doorbell must cover: a directory root guards
- * itself; a single-file root's bell lives on its parent directory (the
- * file's own inode goes deaf on atomic saves).
- */
-export function doorbellGround(root) {
-    return root.kind === 'file' ? parentDirOf(root.path) : root.path;
-}
-/**
- * The root whose OS watcher covers `root`'s doorbell ground, or null
- * when `root` guards itself. The OUTERMOST enclosing directory root
- * wins: with A ⊃ B ⊃ C only A holds a handle, and every deeper root —
- * B, C, nested repos, single files — rides it. A file root can never
- * cover anything.
- */
-export function watchOwnerOf(root, roots) {
-    const ground = doorbellGround(root);
-    let owner = null;
-    for (const other of roots) {
-        if (other.rootId === root.rootId || other.kind === 'file')
-            continue;
-        if (ground !== other.path && !ground.startsWith(`${other.path}/`))
-            continue;
-        if (!owner || other.path.length < owner.path.length)
-            owner = other;
-    }
-    return owner;
-}
-/** Every live root covered by `owner` (owner excluded). */
-export function coveredRoots(owner, roots) {
-    return roots.filter((root) => root.rootId !== owner.rootId
-        && watchOwnerOf(root, roots)?.rootId === owner.rootId);
-}
-//# sourceMappingURL=coverage.js.map

package/dist/detection/coverage.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/detection/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAWH,oDAAoD;AACpD,MAAM,WAAW,GAAG,CAAC,IAAY,EAAU,EAAE;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACxB,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC9C,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAe;IAC5C,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAe,EAAE,KAA2B;IACvE,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,KAAK,GAAqB,IAAI,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QACpE,IAAI,MAAM,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC;YAAE,SAAS;QAC5E,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM;YAAE,KAAK,GAAG,KAAK,CAAC;IACrE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,YAAY,CAAC,KAAgB,EAAE,KAA2B;IACxE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;WACrD,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC,CAAC;AAC3D,CAAC"}

package/dist/detection/suspicion.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"suspicion.d.ts","sourceRoot":"","sources":["../../src/detection/suspicion.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAChC,uFAAuF;IACvF,UAAU,IAAI,IAAI,CAAC;IACnB,uDAAuD;IACvD,QAAQ,IAAI,iBAAiB,CAAC;IAC9B,iEAAiE;IACjE,MAAM,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AASD,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,OAAO,CAGvF;AAED,wBAAgB,oBAAoB,CAAC,GAAG,SAAM,GAAG,cAAc,CAmD9D"}

package/dist/detection/suspicion.js.map

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