@inventarch/service-contracts 3.1.1 → 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 +7 -7
- package/SPEC.md +25 -7
- package/package.json +1 -1
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,6 +1,6 @@
|
|
|
1
1
|
# @inventarch/service-contracts
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/@inventarch/service-contracts) [](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml) [](LICENSE) [](https://www.npmjs.com/package/@inventarch/service-contracts) [](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml) [](LICENSE) [](package.json)
|
|
4
4
|
|
|
5
5
|
> `@inventarch/service-contracts` holds browser-safe structural wire contracts between an independently supplied IA service host and its clients: strict Zod schemas for requests, responses and views, with JSON Schema export. Zod is its only runtime dependency, and importing any export starts no filesystem, network, identity, native runtime, provider or storage work. It stands apart from the `@inventarch/language` to `@inventarch/workspace-runtime` stack and imports none of it.
|
|
6
6
|
|
|
@@ -33,18 +33,18 @@ invalid invalid-request
|
|
|
33
33
|
false
|
|
34
34
|
```
|
|
35
35
|
|
|
36
|
-
`decode` returns the parsed value or throws a `ServiceError` with
|
|
36
|
+
`decode` returns the parsed value or throws a `ServiceError` with category `invalid` and code `invalid-request`. Objects reject unknown fields, so the extra `role` is refused rather than ignored. Four fields accept any JSON value, which the host validates: `invocation.input`, `captureRequest.capture`, `exactQuestionReply.answer` and `publicProposal.candidate`. `failure` turns any error into an `errorResult` for the wire, and `status` maps each error category to its HTTP status. `jsonSchema` returns draft-07 JSON Schema. The package also re-exports `z` from Zod, with `SERVICE_VERSION` and `LIMITS`.
|
|
37
37
|
|
|
38
38
|
## 🧭 What it does
|
|
39
39
|
|
|
40
40
|
| Entry point | Contracts |
|
|
41
41
|
| --- | --- |
|
|
42
|
-
| `.` | Version and limits, binding, offering and operation descriptors, invocation, public sessions and
|
|
42
|
+
| `.` | Version and limits, binding, offering and operation descriptors, invocation and attachment, capture requests and refusals, session start, advance, recovery and control, questions and proposals, public sessions, events, pending items and results, errors (`ServiceError`, `failure`, `status`), strict decoding and JSON Schema |
|
|
43
43
|
| `./tenancy` | Organization, department, membership and workspace commands, views and pages |
|
|
44
|
-
| `./sources` | Exact source references, upload, history and admission, and bounded file chunks |
|
|
44
|
+
| `./sources` | Exact source references, upload, commit, activation, history and admission, and bounded file chunks |
|
|
45
45
|
| `./session-lifecycle` | Session directory summaries, continuation and deadline renewal |
|
|
46
46
|
| `./source-apply` | Exact candidates, preparation, review, application and bounded inspection |
|
|
47
|
-
| `./marketplace` | Native release descriptors,
|
|
47
|
+
| `./marketplace` | Native release descriptors, build, publish and withdraw requests, release pins and terms, catalog pages, the distribution lock, acquisition quotes and receipts, bounded artifact chunks, and registry kit and workspace indexes |
|
|
48
48
|
| `./installation` | Installation planning, explicit review, application and inspection |
|
|
49
49
|
|
|
50
50
|
The `./internal/*` subpaths expose the same pure modules for compatibility; they expand no authority.
|
|
@@ -54,11 +54,11 @@ The `./internal/*` subpaths expose the same pure modules for compatibility; they
|
|
|
54
54
|
- **It validates message shape, nothing more.** Authentication, current tenancy authorization, disclosure filtering, exact source byte verification, semantic admission, replay, scheduler fencing and effects belong to the application host that serves these messages.
|
|
55
55
|
- **Data is never a grant.** Selectors, the permissions a published view lists, command IDs, digests and opaque tokens are data, not authority.
|
|
56
56
|
- **It ships no implementation.** There is no SQL-backed directory, marketplace implementation, transport or inspection method here, only contracts.
|
|
57
|
-
- **Its qualification proves an
|
|
57
|
+
- **Its qualification proves an installable boundary.** Release checks install the packed package in a consumer and import every subpath. A dependency check refuses any import but `zod` and the package's own modules. No browser bundle is built. The checks do not establish hosted authentication, deployment, registry publication or a complete application journey.
|
|
58
58
|
|
|
59
59
|
## 📚 Learn more
|
|
60
60
|
|
|
61
|
-
- [SPEC.md](SPEC.md): the contract for each
|
|
61
|
+
- [SPEC.md](SPEC.md): the contract for each entry point, its error model and limits, and its release qualification.
|
|
62
62
|
- [LANGUAGE.md](LANGUAGE.md): the public vocabulary this release carries.
|
|
63
63
|
- The [root README](../../README.md) and the [architecture reference](../../docs/reference/architecture/README.md).
|
|
64
64
|
- Related: [`@inventarch/runtime`](../runtime/README.md), whose `./authoring` subpath holds the remote authoring client contracts.
|
package/SPEC.md
CHANGED
|
@@ -1,19 +1,37 @@
|
|
|
1
1
|
# Public interoperability contracts
|
|
2
2
|
|
|
3
|
-
Marketplace release terms admit 1–16,384 characters so the complete Apache-2.0 text can be retained; the codec refuses empty/oversized terms. Consumers pinned to the earlier 8,192-character bound require a refreshed artifact. Existing transport bounds remain in force.
|
|
4
|
-
|
|
5
3
|
`@inventarch/service-contracts` owns browser-safe structural service wire contracts under the Apache-2.0 license. Zod is its only runtime dependency. Importing any export initializes no filesystem, network, identity, native runtime, provider or storage. Installed consumers use emitted JavaScript and declarations; development source conditions are removed during packing.
|
|
6
4
|
|
|
7
5
|
| Export | Contract owner |
|
|
8
6
|
|---|---|
|
|
9
|
-
| `.` | Version/limits, binding, offering/operation descriptors, invocation, public sessions/events, errors, strict decoding and JSON Schema |
|
|
7
|
+
| `.` | Version/limits, binding, offering/operation descriptors, invocation and attachment, capture requests/refusals, session start/advance/recovery/control, questions/proposals, public sessions/events/pending/results, errors, strict decoding and JSON Schema |
|
|
10
8
|
| `./tenancy` | Organization, department, membership and workspace commands/views/pages |
|
|
11
|
-
| `./sources` | Exact source references, upload/history/admission and bounded file chunks |
|
|
9
|
+
| `./sources` | Exact source references, upload/commit/activation/history/admission and bounded file chunks |
|
|
12
10
|
| `./session-lifecycle` | Directory summaries, continuation and deadline renewal intent |
|
|
13
11
|
| `./source-apply` | Exact candidates, preparation, review, application and bounded inspection |
|
|
14
|
-
| `./marketplace` | Native release descriptors,
|
|
12
|
+
| `./marketplace` | Native release descriptors, build/publish/withdraw requests, release pins and terms, catalog pages, the distribution lock, acquisition quotes/receipts, bounded artifact chunks, and registry kit and workspace indexes |
|
|
15
13
|
| `./installation` | Installation planning, explicit review, application and inspection |
|
|
16
14
|
|
|
17
|
-
Objects reject unknown fields. Selectors, permissions in a published view, command IDs, digests and opaque tokens are data, never grants. Exact source byte verification, semantic admission, current tenancy authorization, disclosure filtering, replay, scheduler fencing and effects belong to an independently supplied host. No SQL directory, marketplace implementation, transport
|
|
15
|
+
Objects reject unknown fields. Four fields accept any JSON value, which the host validates: `invocation.input`, `captureRequest.capture`, `exactQuestionReply.answer` and `publicProposal.candidate`. Selectors, permissions in a published view, command IDs, digests and opaque tokens are data, never grants. Exact source byte verification, semantic admission, current tenancy authorization, disclosure filtering, replay, scheduler fencing and effects belong to an independently supplied host. No SQL directory, marketplace implementation, transport or inspection method is included. Internal compatibility exports expose the same pure modules; they do not expand authority.
|
|
16
|
+
|
|
17
|
+
## Entry points
|
|
18
|
+
|
|
19
|
+
`.`: `SERVICE_VERSION` is 1. `LIMITS` holds `requestBytes` 768 KiB, `responseBytes` 256 KiB, `pageItems` 100, `offerings` 100 and `operations` 32. An `id` matches `[A-Za-z0-9._-]{1,128}`; a `digest` is 64 lowercase hex characters. An `operationDescriptor` declares one to four effects (`read`, `model`, `write`, `external-write`) and input and output bounds within `LIMITS`; an `offeringDescriptor` holds one to 32 operations. A `publicSession` carries states and counts, never model text, manifests or grants.
|
|
20
|
+
|
|
21
|
+
`.` errors: `decode(schema, value)` returns the parsed value or throws `ServiceError` with category `invalid` and code `invalid-request`. A `ServiceError` carries a category, a code and, optionally, a `capture` refusal checked against `captureFailure`. `failure(error)` returns the `errorResult` `{code, category, message, capture?}` of a `ServiceError`, its message cut to 500 characters, and `{code: 'internal', category: 'internal'}` with a fixed message for any other error. `status` maps each category to its HTTP status: `invalid` 400, `unauthenticated` 401, `forbidden` 403, `not-found` 404, `conflict` 409, `expired` 410, `quota` 429, `unavailable` 503 and `internal` 500. `jsonSchema(schema)` returns draft-07 JSON Schema and throws for a schema it cannot represent.
|
|
22
|
+
|
|
23
|
+
`./tenancy`: each command carries `commandId` and `expectedRevision`, which is 0 for `createOrganizationRequest`. Roles are `owner`, `admin`, `editor` and `viewer`; a department membership cannot grant `owner`. A view carries `commandRevision` only for an administrator. A personal workspace has no organization or department, and an archived workspace's permissions hold no `write` or `execute`. A `directoryReceipt`'s ids must fit its `action`. A page holds at most 100 items and a host-signed `next` cursor of at most 2,048 characters.
|
|
24
|
+
|
|
25
|
+
`./sources`: `SOURCE_LIMITS` holds the source bounds, among them 100 files, 256 KiB per source and 512 KiB per revision. `isOwnedSourcePath` admits a portable NFC path under `.ia/src/` that ends in `.ia`, has at most 500 characters and lies outside `.ia/src/floor/`: no empty, `.` or `..` segment, no segment ending in a dot or a space, no backslash, control or `<>:"|?*` character, and no Windows device name. A source manifest's paths must not collide in letter case. A file chunk request reads at most 32 KiB, returned as base64 `data`.
|
|
26
|
+
|
|
27
|
+
`./session-lifecycle`: a session list page holds at most `LIMITS.pageItems` summaries. A `sessionContinuation` states one of `executable`, `renewal-required`, `runtime-incompatible`, `authority-denied`, `evidence-unavailable`, `unsupported-wait`, `budget-exhausted` or `terminal`, with a renewal `{token, deadline}` or null. A continue request names a new session `id` that differs from `sessionId`.
|
|
28
|
+
|
|
29
|
+
`./source-apply`: a `sourceChangeCandidate` (`ia.source-change.v1`) holds one to 100 changes, sorted by path and distinct in letter case. Each change must change the bytes, and none deletes an absent file. Its new text totals at most 512 KiB. A review states a rationale of 1–4,096 characters. Inspection returns proposals, one application, or a file chunk of at most 32 KiB.
|
|
30
|
+
|
|
31
|
+
`./marketplace`: a `packageId` is a lowercase `<scope>/<name>` of at most 256 characters. A `releaseDescriptor` has `formatVersion` 1 and language `1.0`. `releaseTerms.text` admits 1–16,384 characters, enough for the complete Apache-2.0 text; `license` and `revision` admit 1–128. A `distributionLock` holds 1–100 requests and 1–100 packages. An artifact read asks for at most 96 KiB, and a chunk's `data` holds at most 128 KiB of text. The registry indexes are `ia.registry-kit.v1` and `ia.registry-workspace.v1`, each with at most 1,000 releases.
|
|
32
|
+
|
|
33
|
+
`./installation`: a plan request names `install`, `update` or `remove`. A review states a non-blank rationale of at most 4,096 characters, and an apply names the reviewed plan, digest and decision. An `installationPointer` has `formatVersion` 1 and a counter of at least 1. Inspection reads the `current` installation or one `plan`.
|
|
34
|
+
|
|
35
|
+
## Release qualification
|
|
18
36
|
|
|
19
|
-
The original strict codec tests remain public obligations rather than being renamed or removed. Release qualification
|
|
37
|
+
The original strict codec tests remain public obligations rather than being renamed or removed. Release qualification (`pnpm packages:qualify`) inspects each packed archive's dependencies and exports, checks that no development condition reaches the published `exports`, installs the packed package in a consumer and imports every subpath. `tools/dependencies/check.ts` refuses any import but `zod` and the package's own modules. No browser bundle is built. This proves an installable emitted boundary, not hosted authentication, deployment, registry publication or a complete application journey.
|