@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 +2 -2
- package/README.md +61 -15
- package/SPEC.md +40 -38
- package/dist/checks.d.ts +6 -6
- package/dist/checks.d.ts.map +1 -1
- package/dist/checks.js +8 -8
- package/dist/checks.js.map +1 -1
- package/dist/distribution/contracts.d.ts +1 -1
- package/dist/distribution/contracts.js +1 -1
- package/dist/distribution/contracts.js.map +1 -1
- package/dist/distribution/implementations.d.ts +4 -4
- package/dist/distribution/implementations.js +8 -8
- package/dist/distribution/reader.d.ts +1 -1
- package/dist/distribution/reader.js +1 -1
- package/dist/editor/index.d.ts +2 -2
- package/dist/evidence.d.ts +19 -20
- package/dist/evidence.d.ts.map +1 -1
- package/dist/evidence.js +28 -29
- package/dist/evidence.js.map +1 -1
- package/dist/handle.d.ts +7 -7
- package/dist/handle.d.ts.map +1 -1
- package/dist/handle.js +5 -5
- package/dist/handle.js.map +1 -1
- package/dist/inputs.d.ts +3 -3
- package/dist/inputs.d.ts.map +1 -1
- package/dist/inputs.js +2 -2
- package/dist/inputs.js.map +1 -1
- package/dist/paths.d.ts +2 -2
- package/dist/paths.js +2 -2
- package/dist/preview.js +1 -1
- package/dist/preview.js.map +1 -1
- package/dist/retention.d.ts +1 -1
- package/dist/retention.d.ts.map +1 -1
- package/dist/seat.d.ts +1 -1
- package/dist/seat.d.ts.map +1 -1
- package/dist/view.d.ts +29 -30
- package/dist/view.d.ts.map +1 -1
- package/dist/view.js +25 -25
- package/dist/view.js.map +1 -1
- package/package.json +4 -4
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
|
|
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
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@inventarch/db) [](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml) [](LICENSE) [](package.json)
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
7
|
+
## ⚡ Quick start
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
```sh
|
|
10
|
+
npm install @inventarch/db
|
|
11
|
+
```
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
Read the workspace from the [root README quick start](../../README.md#-quick-start) without writing to it:
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
```js
|
|
16
|
+
import { open } from '@inventarch/db';
|
|
14
17
|
|
|
15
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
22
|
-
# Editor snapshots
|
|
41
|
+
## 🧭 What it does
|
|
23
42
|
|
|
24
|
-
|
|
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
|
-
|
|
61
|
+
The `./internal/*` subpaths serve specific toolchain consumers and are not a stable contract.
|
|
27
62
|
|
|
28
|
-
|
|
63
|
+
## ⚖️ What it does not do
|
|
29
64
|
|
|
30
|
-
|
|
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).
|