@untangle-code/storage-local 0.0.0-stage → 0.1.1

package/NOTICE

@@ -0,0 +1,90 @@
+# NOTICE
+
+Copyright (C) 2026 Luke Bölling and contributors.
+
+This attribution covers original Untangle work. Contributors retain copyright in
+their contributions. Third-party packages, grammars and other materials retain
+their own copyright holders, licenses and notices; this line does not replace them.
+
+## License — binding decision
+
+Untangle is licensed under the **GNU Affero General Public License, Version 3
+(AGPL-3.0-only)**. See [`LICENSE`](./LICENSE).
+
+This decision is **final, not provisional**, and was explicitly instructed by
+the project owner. No contributor, agent or tool may change it without a new
+explicit instruction.
+
+The repository-wide license covers Untangle's first-party source code, scripts,
+tests, fixtures, configuration, documentation, website and brand artwork, including
+the logo and 3D yarn illustrations. Every workspace `package.json` declares
+`"license": "AGPL-3.0-only"`. There is no separately licensed enterprise component
+or separate permissive license for documentation or brand assets.
+
+Third-party code, embedded grammars, dependency assets and their notices retain
+their original licenses. Their inclusion does not relicense those works. The
+repository license does not grant trademark rights or change the license of a
+repository analyzed with Untangle. See the repository's `docs/LICENSING.md` for
+scope and verification details.
+
+This resolves the license question left open in `vision.md` §14 and completes
+`product.md` §16, item 2.
+
+## Rationale
+
+- **Network copyleft fits the intended product model.** AGPL §13 sets source
+  availability requirements for modified versions used through a computer network.
+  The current local CLI/stdio-MCP entry and future shared-server modes share the
+  same license.
+- **Local-first analysis has a clear boundary.** Running Untangle against a codebase
+  does not replace that codebase's own license with Untangle's license.
+- **First-party components share one license.** Implemented components and future
+  official plugins use this repository's licensing policy. Planned integrations do
+  not establish implemented or published products.
+
+## Deliberately accepted consequence
+
+The project deliberately chooses AGPL rather than a permissive embedding license.
+Redistribution, modifications and combined works must be assessed against the
+actual terms in `LICENSE`, including applicable Corresponding Source requirements.
+No permissive exception, commercial dual license or special contract-only package
+license is granted or promised by this notice.
+
+## Dependencies
+
+Third-party runtime dependencies are checked against the allowlist in
+`scripts/check-licenses.mjs`. Their licenses and copyright notices remain unchanged
+and traceable through package `THIRD_PARTY_LICENSES.md` files, grammar provenance,
+the lockfile and release SBOM. The allowlist includes MIT / Apache-2.0 / BSD / ISC
+and other explicitly listed licenses; it is not a license grant for dependencies.
+
+The allowlist in `scripts/check-licenses.mjs` applies to **dependencies**, not
+workspace packages. Untangle's own packages carry AGPL-3.0-only and are excluded
+from that check.
+
+## Clean room
+
+Untangle is an independent implementation with its own data models, APIs, tool
+names, tests and sources. Feature ideas may be derived from publicly observable
+behavior and generally known techniques. Third-party source code is not copied,
+including from AGPL projects even where the license would permit it.
+
+## Contribution terms
+
+Pull requests are welcome under the repository's existing AGPL-3.0-only license.
+No separate CLA, copyright assignment or DCO sign-off is required. Contributors
+must have the right to submit their work under those terms. See CONTRIBUTING.md.
+
+## Release decisions
+
+- [x] Copyright attribution: Luke Bölling, with contributors retaining their rights.
+- [x] Contributions use AGPL-3.0-only without an additional CLA or DCO gate.
+
+## Open legal items before public beta
+
+- [ ] Trademark search for the product name `Untangle`.
+- [ ] Registration and legal review of the npm scope `@untangle-code`.
+- [ ] Verify source availability and notices for each released network daemon/server
+  mode (WP-59). The current stdio MCP `untangle_about` already reports the license,
+  source repository and build commit when supplied; metadata alone does not prove
+  that a concrete deployed version's source is available.

package/README.md

@@ -1,3 +1,227 @@
-# Temporary Holding Version
+# @untangle-code/storage-local
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Untangle local state (WP-12/WP-250): the `.untangle/` layout, a persistent size-bounded embedding
+cache, an atomic checkpoint mirror, a file-based `LockProvider`, and local Search Journey
+persistence. Public package (`private: false`).
+
+Normative sources: [`architecture.md`](../../architecture.md) §12 (layout), §21.1–§21.2 (lock
+architecture), [`spec.md`](../../spec.md) §11.2, §12.3, §13.7, §24 (takes precedence in a conflict),
+[`docs/BUILD_PLAN.md`](../../docs/BUILD_PLAN.md) (WP-12/WP-250).
+
+Dependencies: **only** `@untangle-code/domain` (`workspace:*`) at runtime;
+`@untangle-code/testkit` (`workspace:*`) as a development-only dependency for port contract suites
+and deterministic Clock/Random test doubles. No other Untangle packages or external runtime
+dependencies.
+
+<a id="modulübersicht"></a>
+
+## Module overview
+
+| Module | Contents | Source |
+|---|---|---|
+| `layout.ts` | `StateDirLayout`, `buildStateDirLayout()`, `ensureStateDirLayout()`: architecture.md §12 `.untangle/` directory tree | arch §12 |
+| `local-file-system.ts` | `LocalFileSystem`: `FileSystemPort` adapter over `node:fs/promises`, path sandbox through domain `assertWithinWorkspace` plus symlink recheck | arch §2.1, §23.1 |
+| `lock-provider.ts` | `FileLockProvider`: file-based `LockProvider`, one directory per lock key as an atomic exclusivity primitive, `record.json` written through temp+rename | arch §21.1–§21.2 |
+| `checkpoint-store.ts` | `LocalCheckpointStore`: `CheckpointStorePort`, atomic writes through temp+rename | arch §12, §13.3 |
+| `embedding-cache.ts` | `LocalEmbeddingCache`, `buildEmbeddingCacheKey()`: persistent size-bounded embedding cache with LRU eviction | spec §9.4 |
+| `search-journey-store.ts` | `LocalSearchJourneyStore`: deeply validated, atomic, revision-protected persistence under `.untangle/product-complexity/sessions/`, plus separate HMAC key `.untangle/product-complexity/fingerprint.key` | spec §13.7, §24; WP-250 |
+| `storage.ts` | `openLocalStorage()`: wires all the above adapters to a shared `FileSystemPort` | WP-12 decision |
+| `abort.ts`, `fs-errors.ts`, `real-time.ts` | internal helpers (AbortSignal handling, Node error-code checks, the one isolated real-time source) | internal |
+
+<a id="verwendung"></a>
+
+## Usage
+
+```ts
+import { openLocalStorage } from "@untangle-code/storage-local";
+
+const storage = await openLocalStorage("/abs/path/to/workspace/.untangle", {
+  clock, // Clock (domain port) — real SystemClock in production
+  random, // Random (domain port) — real SystemRandom in production
+});
+
+await storage.embeddingCache.set(profileId, preparedText, vector);
+await storage.checkpoints.save(checkpoint);
+const journey = await storage.searchJourneys.get(sessionId);
+const handle = await storage.locks.acquire(`repo:${repoId}:${refId}:index`, { waitMs: 5_000 });
+```
+
+<a id="entscheidungen"></a>
+
+## Decisions
+
+1. **Lock exclusivity through `FileSystemPort.mkdir` without `recursive`, not a separate locking
+   library.** Node's `mkdir` atomically fails with `EEXIST` if the target directory exists: a real,
+   operating-system-guaranteed exclusivity check directly underlying `FileLockProvider.tryAcquire()`
+   (one directory per `sha256(key)`, containing `record.json`). No extra lock-on-lock mechanism is
+   needed. The test “two provider instances racing for the same fresh lock” proves this with two
+   genuinely concurrent `FileLockProvider` instances in one process. The “lock is free” case is
+   entirely race-free because no takeover step is involved.
+
+2. **Stale-lease takeover is deliberately NOT entirely race-free across processes.** A documented,
+   accepted MVP limit (architecture.md §21.2 itself explicitly calls file locks “MVP”, with a real
+   distributed lease only in “Remote Team Mode”). The takeover window: between “lease recognized
+   as expired” and “orphaned directory removed + recreated” is a TOCTOU window where a holder
+   renewing its lease *at that exact moment* could theoretically be overwritten. The following
+   cases are **not** affected and are therefore tested strictly: (a) contention for a **free** lock
+   (decision 1, fully atomic); (b) distinguishing “directory exists, `record.json` not yet present”
+   (= *busy*, never treated as *stale*, or a competitor still creating its valid lock would lose
+   it to another contender's takeover race); and (c), since the WP-80 fix, “expired” vs. “corrupt”,
+   now two distinct cases that must never be confused (see decision 2a).
+
+2a. **`record.json` is written atomically through a temporary file plus `rename`, both on initial
+    `tryAcquire()` and every `renew()`.** The exact technique already used by this package's
+    `checkpoint-store.ts` (“every write is temporary-file-then-`rename`”). Before this fix (WP-80),
+    initial acquire and renew wrote directly to the live path using `fs.writeFile`. A reader could
+    theoretically see a torn, partially written record; `JSON.parse` failed, and `readRecordState()`
+    treated EVERY parse error as immediately eligible for takeover, regardless of the actual
+    holder's lease (“expired OR corrupt = stale”). Process A writing via `renew()` could be
+    overtaken by B, interpreting the torn intermediate state as “corrupt, therefore free”; both
+    then held the same lock, and A still reported success on its next `renew()`. After the fix,
+    only a single atomic `rename` reaches the live path: readers always see either the old complete
+    record or the new complete record, never a mixture. This guarantee also applies alongside the
+    separate documented TOCTOU gap of stale takeover itself (decision 2). That gap concerns
+    *removing* someone else's apparently stale lock directory, not *writing* one's own record; it
+    remains a separate, previously documented MVP risk.
+
+    **Since the fix, “expired” and “corrupt” are deliberately separate, no longer one “stale”
+    category:**
+    - An **expired lease** (`leaseExpiresAt` in the past) remains immediately eligible for
+      takeover: the lease itself authorizes when the holder is considered to have given up.
+    - An **unreadable (`corrupt`) record** is an ERROR STATE, not a normal lifecycle state. Because
+      every write is now atomic, readers fundamentally cannot see torn records. An actually
+      unparsable `record.json` means external influence (manual editing, disk fault, a record
+      written by an incompatible future format), no longer “caught a write in progress”. A corrupt
+      record also lacks its own trustworthy `leaseExpiresAt`, so unlike an expired lease there is
+      no information on how long it has been invalid. Immediately freeing it would repeat WP-80
+      with a different cause (“I cannot explain it” ≠ “safe to take over”). Selected rule: a
+      **grace period** (`DEFAULT_CORRUPT_GRACE_MS`, `lock-provider.ts`, 5 minutes, substantially
+      longer than any expected lease/write duration), measured from `record.json` file `mtime`.
+      Until that period expires, `tryAcquire()` treats a corrupt record exactly like a validly
+      held lock (`null`, no throw, no takeover attempt). Afterwards it automatically becomes
+      eligible for takeover like an expired lease. This self-heals without operator action while
+      giving a possibly unusually slow legitimate write, or a person investigating the finding,
+      ample time before anybody treats it as abandoned. A `FileLockProvider` constructor parameter
+      can override the grace period, mainly for tests that check the boundary without waiting
+      several real minutes.
+
+3. **Stale detection uses lease expiry only, never PID existence**, exactly as required by
+   architecture.md §21.2. Besides mandatory domain `LockRecordV1` fields, `record.json` contains
+   internal `processStartedAtEpochMs` (the “start time” required by architecture.md §21.2). It never
+   contributes to stale decisions: it is diagnostic information for manually inspecting
+   `record.json`, and is therefore absent from `LockHandle.record` (whose shape is exactly
+   `LockRecordV1`; the domain contract register allows no extension). The test “PID reuse does not
+   cause false takeover” proves this directly: a manually written expired record with
+   `pid: process.pid` (the current test environment apparently “is” the holder) is still correctly
+   taken over because only `leaseExpiresAt` matters.
+
+4. **`renew()` deliberately creates a new `processInstanceId`** rather than retaining the old one.
+   A consistency decision mirroring `InMemoryLockProvider` from `@untangle-code/testkit`. From the
+   record's perspective, renewal is a new “term” of the same holder, identified by the handle
+   itself (which updates its local `current` reference after every `renew()`), not an ID stable
+   throughout the entire holding period.
+
+5. **`LocalFileSystem` symlink checks also cover target paths that do not yet exist**, e.g. a
+   `writeFile()` destination. They start at the nearest *existing* ancestor and resolve it against
+   `assertWithinWorkspace`, rather than checking only existing final paths as a minimal approach
+   would. This catches a *directory* segment symlinking outside the root even when the target file
+   does not yet exist (“rejects writing into a new file under a symlinked directory that escapes
+   the root”). Known limit: a TOCTOU gap remains between the check and actual `node:fs` call. An
+   attacker with filesystem write access could replace a symlink between check and operation.
+   Acceptable for the local single-user MVP described in architecture.md §1, not a sufficient
+   guarantee for multi-user/sandbox isolation.
+
+6. **Checkpoint corruption is reported loudly (`INDEX_INCOMPLETE`), embedding-cache corruption
+   silently degrades to a miss.** Both follow spec.md §25.2 for opposite reasons. A checkpoint is
+   the *only* resume record for an ongoing indexing job. Ignoring corruption would invisibly
+   disguise a real storage error as “no checkpoint exists” (write-path safety reasoning applied to
+   a read path because the underlying issue is consistency, not existence). The embedding cache,
+   by contrast, is explicitly “deletable and reconstructable” under architecture.md §12: a missing
+   or corrupt entry only means “embed this text again”, never data loss. The checkpoint mirror's
+   pointer index (`jobs/latest/<hash>.json`, “which job is latest for this repo+ref”) sits between
+   these and is treated like the cache. It is merely an accelerator over the actual separately
+   integrity-checked checkpoint files; losing it means “no known latest state”, never actual data
+   loss.
+
+7. **The embedding-cache manifest is rewritten completely on every mutation** (`O(number of
+   entries)` per `set()`/`get()` hit), rather than incrementally updating a genuine index. Sufficient
+   at MVP scale (a local workspace cache) and substantially easier to keep correct than a
+   concurrency-safe append log. For very large caches (millions of entries), a real embedded index
+   would be the appropriate next step; deliberately not brought forward because it is outside
+   this assignment.
+
+8. **Two tsconfigs**, as in domain/scanner: `tsconfig.json` (composite, emit to `dist/`, no tests)
+   for the build; `tsconfig.typecheck.json` (`noEmit`, includes tests) for `pnpm run typecheck`.
+   Composite projects do not permit `noEmit`.
+
+9. **Comparable journeys are durable learning artifacts, not telemetry.** Search Journeys exist
+   only after an explicit `start` in the calling service and remain in the workspace-local state
+   directory. The adapter serializes mutations per session, checks a compare-and-swap revision,
+   writes through a temporary file plus atomic `rename`, and deeply validates every record on write
+   and read. The fingerprint-key lock and both the outer creation lock and inner per-session lock
+   use a 30-second lease with non-overlapping renewal attempts every 10 seconds. Immediately before
+   an atomic publish, every held lock is owner-checked and a bounded verification loop requires a
+   shared window with at least 10 seconds remaining on all of them. Losing ownership or failing to
+   converge within eight rounds aborts before `rename` with `LOCK_HELD`. A separate creation lock
+   enforces the 10,000-record ceiling across processes; one record is limited to 32 MiB. Before a list/report parses any
+   record, it builds a file-and-size manifest for the complete snapshot against a 128 MiB
+   cumulative byte budget. Every read rechecks its actual UTF-8 byte count and post-read file size
+   before parsing; disappearance or a size/type change fails the whole report visibly—Untangle
+   never emits a partial cohort as if it were complete. A same-size atomic replacement cannot be
+   distinguished without a versioned file-read primitive and remains a documented local-filesystem
+   snapshot boundary. Corrupt or oversized records likewise fail closed instead of entering a
+   Product-Complexity cohort. Each exact per-write temporary path is removed best-effort after
+   success, cancellation, or I/O failure without reusing the aborted caller signal or masking the
+   primary error.
+
+   The persisted contract is privacy-minimized, not anonymous or encrypted. With the default
+   `retainText: false`, goal/query text and an optional feature ID declared stable by the caller are represented by
+   workspace-local, domain-separated HMAC-SHA-256 fingerprints and no chunk or source content is
+   stored. Untagged legacy journeys are never assigned a feature by the adapter. The random key lives outside
+   session records at `.untangle/product-complexity/fingerprint.key`; anyone with the complete local
+   state and key can test guesses. On POSIX systems, both the key and newly written journey records
+   are created with mode `0600`. Result locators, ranks, scores, explicit tool metadata, a controlled
+   abandonment reason code, and other lifecycle metadata remain. Callers that opt into
+   `retainText: true` additionally persist goal, query, failed-search, and free abandonment text.
+
+   New observations persist measurement context v2. Successful observations do not flatten their
+   profile provenance: embedding profile, generation set, and immutable
+   `corpusRevisionFingerprint` stay bound to the profile that produced them. The revision originates
+   from the completed index's full scanned File-ID/content-hash manifest, including successful
+   zero-change incremental runs. The adapter keeps additive legacy records readable and does not
+   fabricate a revision for them; report derivation leaves them visible but never
+   `sufficientEvidence: true`. Reports are derived rather than stored:
+   `sessionCounts.featureTaggedCompleted` counts completed records with an explicit feature
+   fingerprint, and feature mappings preserve separate Search Journey and accepted-target
+   code-complexity axes.
+
+<a id="bekannte-grenzen-siehe-openissues-im-task-report"></a>
+
+## Known limits (see `openIssues` in the task report)
+
+- No cross-process lock on the embedding cache itself: two processes writing the same key
+  simultaneously overwrite each other without error (last writer wins). Unproblematic for the
+  intended case: one indexing job per ref, already serialized by `LockProvider`.
+- Stale-lock takeover (decision 2) is not covered by real multi-process fuzz testing, only the
+  documented race window and same-process tests. A separate multi-process stress test would be a
+  useful addition but is outside this assignment.
+- **Search Journey records currently have no TTL or delete operation in the port.** `abandon` ends
+  measurement but does not remove its record. Files remain local until workspace state is
+  deliberately cleaned up.
+
+<a id="lizenz"></a>
+
+## License
+
+
+**AGPL-3.0-only.** This package includes the complete license in [`LICENSE`](./LICENSE), the
+license-choice rationale in [`NOTICE`](./NOTICE), and licenses for all third-party production
+dependencies in [`THIRD_PARTY_LICENSES.md`](./THIRD_PARTY_LICENSES.md). All three ship in the npm
+tarball: AGPL-3.0-only §4 and §5 require recipients to receive the license; a README alone is not
+a copy of the license.
+
+Local use alone does not trigger an obligation. Copyleft obligations apply to redistribution and
+providing a network service (AGPL §13).
+
+Corresponding TypeScript source ships under `src/` in the same tarball; the complete repository
+is available at <https://github.com/lboel/untangle>.

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,24 @@
+# Third-party licenses — @untangle-code/storage-local
+
+Generated by `pnpm third-party-licenses` from this package's installed
+production dependency tree: transitive `dependencies`, across
+workspace edges, with no `devDependencies` included. The generator reads
+each resolved package's `package.json` in `node_modules`; nothing is maintained by hand
+or estimated.
+
+Do not edit manually: `pnpm third-party-licenses --check` fails on drift,
+and `pnpm check-publishable` rejects packages without a current file.
+
+This file exists because `docs/BUILD_PLAN.md`, risk R6, makes
+per-package `THIRD_PARTY_LICENSES.md` a release gate for npm publication.
+
+Untangle itself is **AGPL-3.0-only** (see `LICENSE` and `NOTICE` in
+this package). The packages below are third-party works; their own
+licenses and copyright notices continue to apply unchanged. Workspace
+packages (`@untangle-code/*`) are not listed here; they belong to the same
+work and use the same AGPL-3.0-only license.
+
+## Result: no third-party dependencies
+
+This package has no production dependencies outside the workspace.
+The list is empty because none exist, not because they were not checked.

package/dist/abort.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared `AbortSignal` handling (spec.md §22: "public APIs MUST support
+ * abort signals"; rule 9: every long-running method respects `AbortSignal`
+ * and aborts with `JOB_CANCELLED`).
+ *
+ * Every port method in this package is `async`, so throwing synchronously
+ * here still surfaces as a rejected Promise to the caller — unlike
+ * `@untangle-code/testkit`'s `abortedRejection` (which exists specifically
+ * for a few NON-`async` methods where a synchronous throw would be a bug).
+ */
+import type { PortCallOptions } from "@untangle-code/domain";
+/** Throws `UntangleError("JOB_CANCELLED", …)` when `options.signal` is already aborted. */
+export declare function assertNotAborted(options: PortCallOptions | undefined, operation: string): void;
+/** Builds a `PortCallOptions` from an optional `AbortSignal` without ever setting
+ * `signal: undefined` explicitly — required because domain's `PortCallOptions` is
+ * checked under `exactOptionalPropertyTypes`. */
+export declare function portOptions(signal: AbortSignal | undefined): PortCallOptions | undefined;
+//# sourceMappingURL=abort.d.ts.map

package/dist/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAI9F;AAED;;iDAEiD;AACjD,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAExF"}

package/dist/abort.js

@@ -0,0 +1,14 @@
+import { UntangleError } from "@untangle-code/domain";
+/** Throws `UntangleError("JOB_CANCELLED", …)` when `options.signal` is already aborted. */
+export function assertNotAborted(options, operation) {
+    if (options?.signal?.aborted) {
+        throw new UntangleError("JOB_CANCELLED", `"${operation}" was aborted`, { operation });
+    }
+}
+/** Builds a `PortCallOptions` from an optional `AbortSignal` without ever setting
+ * `signal: undefined` explicitly — required because domain's `PortCallOptions` is
+ * checked under `exactOptionalPropertyTypes`. */
+export function portOptions(signal) {
+    return signal === undefined ? undefined : { signal };
+}
+//# sourceMappingURL=abort.js.map

package/dist/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,2FAA2F;AAC3F,MAAM,UAAU,gBAAgB,CAAC,OAAoC,EAAE,SAAiB;IACtF,IAAI,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,aAAa,CAAC,eAAe,EAAE,IAAI,SAAS,eAAe,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACxF,CAAC;AACH,CAAC;AAED;;iDAEiD;AACjD,MAAM,UAAU,WAAW,CAAC,MAA+B;IACzD,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;AACvD,CAAC"}

package/dist/analysis-cache.d.ts

@@ -0,0 +1,81 @@
+import type { AnalysisCacheKind, Clock, FileSystemPort, PortCallOptions, Random } from "@untangle-code/domain";
+export { ANALYSIS_CACHE_KINDS, buildChunkCacheKey, buildMetricsCacheKey, buildParseCacheKey, type AnalysisCacheKind, type AnalysisIdentityKeyPartsV1, } from "@untangle-code/domain";
+/** 256 MiB je Cache — eine Untangle-Vorgabe, keine Spec-Zahl. */
+export declare const DEFAULT_ANALYSIS_CACHE_MAX_BYTES: number;
+/** Nach so vielen Mutationen wird das Manifest geschrieben. */
+export declare const MANIFEST_FLUSH_INTERVAL = 64;
+export interface ContentCacheStatsV1 {
+    entryCount: number;
+    totalBytes: number;
+    /** Treffer seit dem Oeffnen dieses Cache-Objekts. */
+    hits: number;
+    /** Fehlschlaege seit dem Oeffnen dieses Cache-Objekts. */
+    misses: number;
+    /** Trefferquote in [0,1]; 0, wenn nichts nachgeschlagen wurde. */
+    hitRate: number;
+    /** Wie viele Eintraege die Groessengrenze verdraengt hat. */
+    evictions: number;
+}
+/**
+ * Ein inhaltsadressierter JSON-Cache mit Groessengrenze, Verdraengung und
+ * Trefferquote. Der Schluessel ist eine undurchsichtige Zeichenkette; wer ihn
+ * baut, verantwortet seine Vollstaendigkeit (siehe Kopf dieser Datei).
+ */
+export declare class LocalContentCache {
+    private readonly fs;
+    private readonly dir;
+    private readonly clock;
+    private readonly random;
+    private readonly maxBytes;
+    private manifest;
+    private dirty;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(fs: FileSystemPort, dir: string, clock: Clock, random: Random, options?: {
+        maxBytes?: number;
+    });
+    private manifestPath;
+    private entryFileName;
+    private entryPath;
+    private loadManifest;
+    private persistManifest;
+    private touched;
+    /** Schreibt das Manifest, falls Mutationen ausstehen. Am Ende eines Laufs aufrufen. */
+    flush(options?: PortCallOptions): Promise<void>;
+    /** Der Wert, oder `null` fuer "nicht im Cache". Wirft nicht fuer kaputte Eintraege. */
+    get(logicalKey: string, options?: PortCallOptions): Promise<unknown | null>;
+    set(logicalKey: string, value: unknown, options?: PortCallOptions): Promise<void>;
+    private evictUntilWithinLimit;
+    stats(options?: PortCallOptions): Promise<ContentCacheStatsV1>;
+    /** Loescht ausschliesslich das eigene Verzeichnis dieses Caches. */
+    clear(options?: PortCallOptions): Promise<void>;
+}
+/** Trefferquoten aller drei Caches, einzeln und zusammen. */
+export interface AnalysisCacheStatsV1 {
+    parse: ContentCacheStatsV1;
+    chunk: ContentCacheStatsV1;
+    metrics: ContentCacheStatsV1;
+    totalHits: number;
+    totalMisses: number;
+    /** Trefferquote ueber alle drei Caches in [0,1]. */
+    hitRate: number;
+}
+/**
+ * Die drei Caches als ein Gegenstand — genau die Form, die
+ * `@untangle-code/core` als `AnalysisCacheLike` erwartet.
+ */
+export declare class LocalAnalysisCache {
+    readonly parse: LocalContentCache;
+    readonly chunk: LocalContentCache;
+    readonly metrics: LocalContentCache;
+    constructor(parse: LocalContentCache, chunk: LocalContentCache, metrics: LocalContentCache);
+    private of;
+    get(kind: AnalysisCacheKind, key: string, options?: PortCallOptions): Promise<unknown | null>;
+    set(kind: AnalysisCacheKind, key: string, value: unknown, options?: PortCallOptions): Promise<void>;
+    /** Schreibt die Manifeste aller drei Caches. */
+    flush(options?: PortCallOptions): Promise<void>;
+    stats(options?: PortCallOptions): Promise<AnalysisCacheStatsV1>;
+    clear(options?: PortCallOptions): Promise<void>;
+}
+//# sourceMappingURL=analysis-cache.d.ts.map

package/dist/analysis-cache.d.ts.map

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