@inventarch/db 3.1.0 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LANGUAGE.md CHANGED
@@ -22,7 +22,7 @@ Spec source locators do not load documents. Resource capture and disclosure requ
22
22
  | @convention | governance-system | Declares a convention in the shared governance shape. |
23
23
  | @decision | work-system | Represents a choice that is needed or has been made: the question, options and decider, and once made, the choice and rationale. |
24
24
  | @dimension | taxonomy | Defines a supported record dimension used by conditions and lookup. |
25
- | @distribution | workspace-system | Declares root records from which a distributable closure is selected. |
25
+ | @distribution | workspace-system | Declares root records from which a distributable closure is selected, and optionally the host plugin product it describes. |
26
26
  | @execution-binding | agent-composition-system | Connects a native target to a host-installed entry or operation descriptor. |
27
27
  | @harness | agent-composition-system | Composes profiles and execution bindings in a workspace under a host contract. |
28
28
  | @hook | hook-authoring-system | Represents a host event, tool/path selection and guard message. Registration and executing a guard require a host adapter. |
@@ -40,7 +40,7 @@ Spec source locators do not load documents. Resource capture and disclosure requ
40
40
  | @placement | taxonomy | Defines source authority and reach metadata. |
41
41
  | @plan | work-system | Represents an arrangement of milestones toward an intent; it heads the work hierarchy and has no parent. Plans do not nest. |
42
42
  | @playbook | governance-system | Represents a procedure as phase/primitive cells. Cell delivery is generic; the authored method belongs to its author. |
43
- | @predicate | taxonomy | Defines a directed relationship and its inverse spelling. |
43
+ | @predicate | taxonomy | Defines a directed relationship, its inverse spelling and its present phrase. |
44
44
  | @primitive | taxonomy | Defines a cognitive primitive coordinate; a cell is selected using its phase and primitive. |
45
45
  | @principle | governance-system | Declares a governing rationale in the shared governance shape. |
46
46
  | @run | session-system | Represents a governed run identity, declared phase, status and owner. Declaration does not start execution. |
package/README.md CHANGED
@@ -1,30 +1,76 @@
1
1
  # @inventarch/db
2
2
 
3
- Filesystem composition of language, graph and compliance. [SPEC.md](SPEC.md) owns admitted views, revisions, read scopes and the disposable cache.
3
+ [![npm](https://img.shields.io/npm/v/@inventarch/db?label=npm)](https://www.npmjs.com/package/@inventarch/db) [![Public quality](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml/badge.svg?branch=main)](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml) [![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE) [![Node](https://img.shields.io/badge/node-%3E%3D22.22.0%20%3C23-brightgreen)](package.json)
4
4
 
5
- Use `open(workspacePath)` to discover `.ia/src`, then `resolveScope({root, phase})` and pass its `token` as `within` to `snapshot`, `records`, `get`, `referencedBy`, `directedView`, `resolveSeat`, `words`, `roots`, `resolve`, `search` and `traverse`. Runtime consumers must use tokens. Unscoped methods and independent scope issuance are privileged host inspection. A child scope intersects physical occurrences; changing its effective registry refuses. Identity allowlists only narrow. `report` and `refused` expose root-view admission evidence to the privileged host. A snapshot's `membership` gives each of its records one `{identity, root, band, digest}` row: the source root it was captured under (the longest root that a `@workspace` admitted at the workspace root declares in `sources`, else its system folder), its band and its per-record digest (SPEC D02a). Every scope gives an occurrence the same row. `directedView(identity)` lists the identity's declared edge rows, the derived inverses of its counterparts' declarations (read from its side in the kernel spelling, such as `governed-by` at the target, with the record that declared them) and its typed field references both ways, rows whose counterpart is outside the scope pruned (SPEC D09, graph G06b). `resolveSeat(path)` resolves a workspace-relative path to the seat it is declared at, `by` naming the rule: the `@system` of the system folder holding it (`system`), else the `@workspace` declaring the longest `sources` root containing it (`root`), else, for a path in no `.ia` tree, the repository's own `@workspace` (`repository`); with no seat, `unknown` reads `undeclared`, or `outside` for a path that is absolute or escapes the workspace. Its `claimants` are the records whose `covers` (a `@check`'s `check.covers` included) or `hook.paths` selections select the path (a `@check`'s textual `check.scope` claims nothing), band descending then identity, each with the matching fields and selections (SPEC D02b, graph G06c). A scope prunes the seat and the claimants like a search. `words()` lists the words the view's registry registers for its admitted systems, the floor's two included, sorted: the closed set a runtime scope key's word must belong to (SPEC D09a). A child scope never changes it, so every scope of a view reads the same words; a scope issued for another root reads that root's view, whose registry may admit other systems. The registry itself stays private. `roots()` lists the roots the `@workspace` records declare in `sources` as `{root, placement, workspace}`, longest first, so a reader can tell a workspace's capture members from the rest; a scope that does not admit the declaring workspace prunes its roots, never re-rooting a row (SPEC D02c).
5
+ > `@inventarch/db` reads an IA workspace from disk. It discovers the workspace's `.ia/src` sources, installed distributions and adopted mounts, admits them through `@inventarch/language`, `@inventarch/graph` and `@inventarch/compliance`, and serves the admitted records through scoped read handles. [`@inventarch/runtime`](../runtime/README.md), the `ia` CLI and the other IA apps read workspaces through it.
6
6
 
7
- `refresh()` rebuilds and verifies stable inputs before replacing the state. A failed refresh preserves the previous view. A source change stales existing scopes even if those bytes are subsequently restored. `close()` refuses future reads. Cached root graphs are always verified against a fresh build; corrupt or forged payloads are replaced, equal bytes are not rewritten, and unavailable cache storage leaves in-memory reads usable with a warning. Set `cache:false` for a fully read-only open.
7
+ ## ⚡ Quick start
8
8
 
9
- `authoredRevision` on a handle, and on each snapshot, is the revision without the sources at runtime placement (graph `authoredRevisionOf`, the derived `.ia/.db-inputs.json` input kept), so a runtime-band source such as the evidence an `ia validate` writes moves `revision` and leaves it (one that adds no system folder and declares no `@system` or `@schema`, which the kept input and the registry name), while an authored edit moves both; it equals `revision` while no source sits at runtime placement (SPEC D05a). Scopes, `revision` read bindings (`IA-DB-STALE`), previews and the cache keep `revision`; retention and the capture pair key on the authored revision.
9
+ ```sh
10
+ npm install @inventarch/db
11
+ ```
10
12
 
11
- A handle also retains the previous admitted root snapshot: the most recent one whose authored revision differs from the current one, so opening or refreshing at an unchanged authored revision keeps it (SPEC D08). `previousRevision` and `previousAuthoredRevision` name it. `staleness(identity)` compares the identity's current membership digest with the previous one's and answers `unchanged`, `changed`, `new` (every current identity while no previous snapshot is retained) or `removed`; `readiness(identity, digest)` answers `current`, `previous` or `unknown` for a digest observed earlier, such as an `@observation`'s `subject-revision`. Both take the same `within`, `root`, `phase` and `revision` bindings as `get`, answer about the record `get` returns, and refuse an identity outside the scope with `IA-DB-OUT-OF-SCOPE`. Only root snapshots are retained: when a narrower root or phase reads an occurrence other than the root one, `staleness` is undefined and `readiness` answers only `current` or `unknown`. The pair persists between processes as the capture pair `ia capture` writes through `writeCapture(root, text)`: `.ia/work/snapshot/current.json` and `previous.json`, `ia-snapshot-1` documents (SPEC D08a). Every disk handle, whatever its cache setting, seeds its previous snapshot from that pair the first time it is asked, never on open or refresh, and never writes it; `capturedRevision` and `capturedAuthoredRevision` name the revision and the authored revision of the capture at `current.json`, which a capture written before the authored revision names by its `revision`; a capture whose records not at runtime placement are the fresh ones, by identity, band and digest, is trusted at the fresh authored revision whatever its runtime-band rows and roots, while a runtime-band record that changes which of them are admitted leaves it untrusted until the next capture. A file that is no capture, or one behind a link, is ignored and every read stays usable. A refresh rotates the pair in memory without reading the capture pair, so a handle that lived through an edit reports it whether or not it was captured, and `capturedRevision` is read again when next asked. `writeCapture` counts the records against the prior capture by digest, rotates the prior `current.json` into `previous.json` on an authored revision change, writes nothing until its checks pass (a link, a `.ia/work` or snapshot directory that is not a directory, a snapshot path that is not a regular file) and leaves the pair it found when a write fails. `planCapture(root, text)` makes the same checks and reads and returns what `writeCapture` would (its counts and rotation) with the changed, added and removed identities, each list sorted; it creates and writes nothing, which is how `ia capture --preview` reports a capture without spending the retained previous snapshot.
13
+ Read the workspace from the [root README quick start](../../README.md#-quick-start) without writing to it:
12
14
 
13
- `inertDeclarations(options)` names the declarations the capture reads that declare nothing, each with its record, field, value, path, line and reason: a `composition.sources` entry that names no root, and a path selection the dialect reads as none (SPEC D02b). They are not admission findings.
15
+ ```js
16
+ import { open } from '@inventarch/db';
14
17
 
15
- An adopted mount bound in `.ia/workspace.json` has its sources labelled `.ia/adopted/<id>/<revision>/…`, under which no file exists; `adoptedBindings(root)` returns each binding `{id, path, revision, tree}` with that label as `tree`, so a host reads the mount's other files from `path`. `sourceTree(path)` names the tree a source path belongs to: '' for the workspace's own `.ia/src`, else the directory above its `.ia/src`, or the label of an adopted mount (SPEC D02a).
18
+ const workspace = open('path/to/your-project', { cache: false });
19
+ try {
20
+ const { token } = workspace.resolveScope();
21
+ const decision = workspace.get('work-system/definition/decision/api-response-format', { within: token });
22
+ console.log(decision.band, decision.source.path);
23
+ console.log(workspace.resolveSeat('.ia/src/decision.ia', { within: token }));
24
+ } finally {
25
+ workspace.close();
26
+ }
27
+ ```
16
28
 
17
- `readWorkspaceBytes(root, path, limit)` reads one workspace file's exact bytes for a host, such as the document a record names: a path that escapes the workspace, is not portable by the rule the distribution workspace file reader applies, or passes a link or junction, a hard-linked or nonregular file and a file of more than `limit` bytes refuse, as package source capture refuses them, and every refusal names the file by its canonical path alone (SPEC D01a). The runtime Door's `read` reads documents through it.
29
+ ```text
30
+ 100 .ia/src/decision.ia
31
+ {
32
+ path: '.ia/src/decision.ia',
33
+ seat: 'workspace-system/definition/workspace/my-project',
34
+ by: 'root',
35
+ claimants: []
36
+ }
37
+ ```
18
38
 
19
- The package writes no authored source. An explicit `floor` wins; otherwise an existing local floor directory is authoritative as a whole, and an absent local directory uses the language's generated source embed. Higher systems are never implicit. Paths escaping the workspace, source aliases and invalid UTF-8 refuse by name. Per-source `locations` supply explicit placement/provenance overrides. No source writer, and no retention beyond the current and previous root snapshots, is implemented.
39
+ `open` admits the workspace once. `resolveScope` issues an opaque token, and every read that passes it as `within` stays inside that scope. Band 100 marks a record the workspace authors. `cache: false` makes the open fully read-only. Without it, the handle keeps a disposable graph cache at `.ia/.iadb/graph.json`; a handle opened with `checks: 'structural'` or `evidence: true` never reads or writes that cache. The `.ia/.gitignore` that `ia init` writes does not list `.iadb/`, so add it to your ignore file.
20
40
 
21
- `preview([{path,text}])` validates an in-memory draft against the current source snapshot through the same admission pipeline. It returns base/candidate revisions, admitted records and full refusal/report evidence without mutating files, caches, scopes or the handle. It is a privileged authoring-host API; callers must check current source freshness before using its result. Floor edits and malformed/aliased draft paths refuse.
22
- # Editor snapshots
41
+ ## 🧭 What it does
23
42
 
24
- Installed native distributions are discovered through `.ia/distributions/active.json` and the matching portable lock. Every fresh snapshot verifies selected manifests, complete file inventories, generation bytes and compatibility before ordinary admission. Sources retain their physical store paths and adopted placement; the generated installation workspace records direct distribution use. Missing/corrupt/drifted state and pending recovery refuse instead of silently dropping content. Database reads perform no installation write or network access. The public `@inventarch/db/distribution` entrypoint owns shared strict decoders and candidate-generation verification for the installer.
43
+ | Export | Use it for |
44
+ | --- | --- |
45
+ | `open(root, options)` | Discover and admit a workspace and return a `Handle`. `checks: 'structural'` admits `@check` records the way `ia validate`, `ia preview` and `ia author` do. `evidence: true` also reads the evidence recorded for the current authored revision, at runtime placement (band 0). `adopted`, `authoredRoots`, `floor` and `locations` replace discovered inputs; see [SPEC.md](SPEC.md). |
46
+ | `resolveScope(request)` | Issue a scope token for a root, a phase or a list of identities. A child scope only narrows. |
47
+ | `get`, `records`, `snapshot`, `search`, `traverse`, `resolve`, `referencedBy`, `directedView` | Read admitted records and their relationships through a token. |
48
+ | `resolveSeat`, `roots`, `words` | Find the seat a path is declared at and the records that claim it, the declared source roots, and the registered words. |
49
+ | `report`, `refused`, `unadmitted` | Admission findings and the records admission left out, for privileged host inspection. |
50
+ | `revision`, `authoredRevision`, `staleness`, `readiness`, `refresh()` | Track change. The authored revision leaves out runtime-placed sources such as `ia validate` evidence; `staleness` and `readiness` compare a record with the previous retained snapshot. |
51
+ | `preview(changes)` | Admit in-memory drafts against the current sources without writing anything. |
52
+ | `planCapture`, `writeCapture` | Plan or write the capture pair under `.ia/work/snapshot/` that `ia capture` maintains. |
53
+ | `bindChecks`, `writeEvidence`, `readEvidence` | Bind each `@check` to an evaluator and keep the `@observation` evidence `ia validate` records under `.ia/work/evidence/`. |
54
+ | `writeRunnerEvidence` | Record a verified runner journal under `.ia/work/runner-evidence/`. |
55
+ | `readWorkspaceBytes(root, path, limit)` | Read one workspace file's exact bytes, refusing links, escaping paths and files over the limit. |
56
+ | `DbError`, `DB_CODES` | Every operational refusal is a `DbError`. Its `code` is one of the eleven `IA-DB-*` codes in `DB_CODES`, and its optional `path` names the workspace-relative entry at fault. An installation refusal is an `InstallationError` from `@inventarch/db/distribution`, a `DbError` that adds a `reason`. A `readWorkspaceBytes` limit or a capture text of the wrong form is a `TypeError`. |
57
+ | `@inventarch/db/editor` | `EditorDatabase` and `EditorSnapshot`: cache-free readers with unsaved overlay buffers. |
58
+ | `@inventarch/db/distribution` | Strict decoders and canonical bytes for release descriptors, manifests, locks, generation membership, activation pointers and the installed-implementation catalog, and `readInstalledGeneration`, which verifies the active installed generation. |
59
+ | `@inventarch/db/descriptors` | Pure, bounded compilers for `domain-model`, `storage-binding` and `app-composition` descriptor resources; see [their contract](src/descriptors/SPEC.md). |
25
60
 
26
- Activation identity and its monotonic counter participate in view/source revisions, including editor overlays and draft previews. Rollback therefore cannot revive prior scopes. The host-only `candidateInstallation` option selects a verified staged pointer for admission; explicit `null` captures authored/bound sources without an installation. Editor metadata reports installed sources and generated installation state as read-only. Matching authored system declarations may override installed authority only under the locked provider/version contract and ordinary whole-tree admission.
61
+ The `./internal/*` subpaths serve specific toolchain consumers and are not a stable contract.
27
62
 
28
- `@inventarch/db/editor` provides `EditorDatabase` and immutable `EditorSnapshot` readers. Overlay buffers (including explicit deletion) reuse normal discovery, registry, graph and admission rules without writing source/cache files. Reads preserve the existing location/phase/scope restrictions. Editor readers retain no previous snapshot: `previousRevision` is undefined, `staleness` reads `new` for every current identity and `readiness` never answers `previous`. Captures expose saved/dirty/source-origin/version metadata; embedded sources remain read-only. Failed refresh retains the last reader; hosts must surface unavailability and refuse stale actions. See the colocated spec and editor tests.
63
+ ## ⚖️ What it does not do
29
64
 
30
- `@inventarch/db/descriptors` compiles OS09 domain, storage and app descriptor resources against a host-built trusted registry without I/O or code execution; see [its SPEC](src/descriptors/SPEC.md).
65
+ - **It never writes authored source.** Its only writes are the disposable cache, which `cache: false` turns off, and the capture pair and evidence files, each only when you call its writer.
66
+ - **It makes no network request and no installation write.** Reads verify installed distributions and refuse missing, corrupt or drifted state. Acquiring and installing archives belongs to the application, such as the `ia` CLI.
67
+ - **Admission is not evaluation.** Opening a workspace runs no conformance suite or prose case. `bindChecks` runs no evaluator that is not built in: such a check stays `not-evaluated`, which is never a pass.
68
+ - **A scope narrows reads; it does not decide who reads.** Unscoped reads and issuing independent scopes are privileged host inspection, and the host that holds the handle decides what it discloses. Call `isCompleteScope(token)` before you show `report`, `refused` or `unadmitted` to a reader: only a whole-workspace scope may disclose them.
69
+ - **Evidence is not attestation.** A runner journal's hash chain establishes internal integrity, not an external observer, authorized execution or real-world effects.
70
+
71
+ ## 📚 Learn more
72
+
73
+ - [SPEC.md](SPEC.md): the database contract for revisions, scopes, retention, capture and evidence.
74
+ - [LANGUAGE.md](LANGUAGE.md): the public vocabulary this release carries.
75
+ - The [root README](../../README.md) and the [architecture reference](../../docs/reference/architecture/README.md).
76
+ - Related packages: [`@inventarch/language`](../language/README.md), [`@inventarch/graph`](../graph/README.md), [`@inventarch/compliance`](../compliance/README.md) and [`@inventarch/runtime`](../runtime/README.md).