@inventarch/language 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 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,6 +1,6 @@
1
1
  # @inventarch/language
2
2
 
3
- [![npm](https://img.shields.io/npm/v/@inventarch/language?label=npm)](https://www.npmjs.com/package/@inventarch/language) [![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-22.x-brightgreen)](package.json)
3
+ [![npm](https://img.shields.io/npm/v/@inventarch/language?label=npm)](https://www.npmjs.com/package/@inventarch/language) [![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
5
  > The `.ia` language in pure TypeScript: one scanner, one parser, an explicit vocabulary registry, a semantic compiler, a loss-checked formatter and the embedded language floor. Use it to parse, register, compile and format IA text, or to edit one record of a source file.
6
6
  >
@@ -41,19 +41,23 @@ console.log(format(source, 'decision.ia').text);
41
41
  | Export | What it does |
42
42
  | --- | --- |
43
43
  | `scan(text, path)`, `parse(text, path)` | The token stream with trivia; `{ ast, diagnostics }` with records, typed fields, nesting, comments and line spans |
44
- | `buildRegistry(sources)` | Joins the `@system` and `@schema` declarations of parsed sources into a frozen registry. Only `system` and `schema` are built in; every other word needs a registration |
45
- | `compile(ast, registry, location, pool)` | `{ records, diagnostics, sourceMap }`: identities, typed fields, relationship edges with two-sided consent, cells, selectors, variants and contract requirements |
44
+ | `buildRegistry(sources)` | `{ registry, diagnostics }`: a frozen registry joined from the `@system` and `@schema` declarations of parsed sources, and the stage diagnostics. Only `system` and `schema` are built in; every other word needs a registration |
45
+ | `compile(ast, registry, location, pool)` | `{ records, diagnostics, sourceMap }`: identities, typed fields, relationship edges with two-sided consent, cells, selectors, variants and contract requirements. `pool` holds the admitted records of other files; a record from this file's path in `pool` is a `TypeError` |
46
46
  | `resolveTarget`, `validatePool`, `requirementCollisions` | Reference resolution and whole-tree requirement uniqueness for callers that assemble many files |
47
47
  | `format(source, path)`, `checkFormatPreservation(source, output, path)` | Canonical spacing that keeps comments, blank lines and multiline values; the guard reports `IA-LANG-FORMAT-LOSSY` when a candidate changes them |
48
48
  | `references(ast)` | The typed references a file holds; prose is never read as a reference |
49
49
  | `identityOf`, `renderIdentity`, `canonicalPath`, taxonomy constants and `is*` guards | Identity, path and closed-value helpers such as `KINDS`, `PHASES`, `PREDICATES`, `INVERSE_OF` and `VERB_PHRASES` |
50
50
  | `KERNEL_SOURCES`, `KERNEL_DIGEST` | The validated language floor as frozen path and text sources, and its digest |
51
+ | `LANGUAGE_VERSION`, `SUPPORTED_VERSIONS` | The language version this package reads (`1.0`); graph's `load` and `revisionOf` take it as `languageVersion` |
52
+ | `LANG_CODES`, `consentFor`, `verbOf`, `canonicalValue` | The closed `IA-LANG-*` diagnostic codes, two-sided consent for one edge, and lookups of verb spellings and closed values |
53
+
54
+ A `Location` is `{ placement: { kind, band, reach }, provenance }`. Give it the band `BAND_OF[kind]`: graph's `load` refuses any other with a `TypeError`. Each `buildRegistry` source is `{ ast, diagnostics, location }`, such as `{ ...parse(text, path), location }`. The [graph quick start](../graph/README.md#-quick-start) compiles `KERNEL_SOURCES` this way.
51
55
 
52
56
  The `./editor` subpath serves editors and authoring hosts:
53
57
 
54
58
  | Export | What it does |
55
59
  | --- | --- |
56
- | `projectSource`, `cursorContext`, `lineRange`, `recordsIn` | Zero-based UTF-16 ranges for tokens and references, and presentation-only cursor context |
60
+ | `projectSource`, `cursorContext`, `lineRange`, `recordsIn`, `contains` | Zero-based UTF-16 ranges for tokens and references, and presentation-only cursor context |
57
61
  | `appendRecord`, `addRelationship`, `setField`, `annotateRecord` | Return the whole file with exactly one top-level record changed; every other line keeps its bytes and line ending |
58
62
  | `draftSource`, `encodeValue`, `draftValue`, `relationshipConsent` | Spell a schema-backed draft or one field value, and judge one relationship row's two-sided consent |
59
63
  | `SourceEditError` | Thrown by a refused edit, with a closed `reason` such as `parse`, `identity` or `field` |
package/SPEC.md CHANGED
@@ -1,14 +1,12 @@
1
1
  # Language package specification
2
2
 
3
- `tests/edit-source.test.ts` pins E04's sibling-byte preservation for set-field, relationship, append and annotation edits on mixed LF/CRLF files. The cases exercise either initial ending, a BOM, noncanonical spacing and a final record with or without a terminating newline; byte comparisons do not normalize the untouched text.
4
-
5
- **Owner:** `@inventarch/language`. **Current status:** syntax, registration, structured and semantic compilation, native kernel generation and loss-checked formatting are implemented. Sections 1–9 retain the original baseline at `69c75b7`; their statements of missing behavior are historical. Sections 10–12 supersede those limits and define the delivered semantic/format/kernel contracts. Downstream graph, compliance, database, runtime and local executable consumers have also shipped. Editor and development harness implementations have their own contracts and qualification; their existence does not change language ownership.
3
+ **Owner:** `@inventarch/language`. **Current status:** syntax, registration, structured and semantic compilation, native kernel generation, loss-checked formatting and the editor surface are implemented. Sections 1–9 keep the original baseline contract; their statements of missing behavior are historical. Sections 10–13 supersede those limits and define the delivered semantic, format, kernel and editor contracts. Downstream graph, compliance, database, runtime and local executable consumers have also shipped. Editor hosts and development harnesses have their own contracts and qualification; their existence does not change language ownership.
6
4
 
7
5
  This file distinguishes delivered package behavior from future obligations; it does not turn an implementation gap into permission to ignore a language rule.
8
6
 
9
7
  ## 1. Responsibility and dependencies
10
8
 
11
- L01. The package owns the shared scanner, parser, vocabulary/schema declarations, identity and compilation. Public entrypoints are exported by [src/index.ts](src/index.ts). It has no runtime dependency on another workspace package, no filesystem access, clock, randomness, model client or implicit corpus. Callers supply text, paths, registries, locations and candidate records.
9
+ L01. The package owns the shared scanner, parser, vocabulary/schema declarations, identity and compilation. Public entry points are the root, exported by [src/index.ts](src/index.ts), and `./editor`, exported by [src/editor/index.ts](src/editor/index.ts) (section 13). It has no runtime dependency on another workspace package, no filesystem access, clock, randomness, model client or implicit corpus. Callers supply text, paths, registries, locations and candidate records.
12
10
 
13
11
  L02. The floor has exactly two reserved record discriminators: `system` and `schema`. Other words require a successful registration. The embedded taxonomy supplies seven kinds, fifteen categories, four phases, six primitives, five moves, eighteen active predicates with inverses, severity/provenance, placements, value types and cardinalities. Nine routing-axis names exist; lane/shape/artifact-set values and present-tense verb phrases are a later addition (section 10).
14
12
 
@@ -21,12 +19,12 @@ L03. This package emits diagnostics, not compliance verdicts. Registry validatio
21
19
  | `scan(text, path)` | One stream with source positions, trivia and scanner diagnostics | [scanner](src/scanner/index.ts), [scanner tests](tests/scanner/scan.test.ts) |
22
20
  | `parse(text, path)` | `{ ast, diagnostics }`; AST includes records, typed fields/items, nesting and trivia | [parser](src/parser/index.ts), [record tests](tests/parser/records.test.ts) |
23
21
  | `buildRegistry(sources)` | Each source supplies AST, parser diagnostics and location; returns resolved registry and stage diagnostics | [registry](src/registry/index.ts), [join tests](tests/registry/index.test.ts) |
24
- | `compile(ast, registry, location, pool)` | Returns lowered records, compile diagnostics and source maps; baseline ignores pool | [compiler](src/compile/compile.ts), [compile tests](tests/compile/compile.test.ts) |
22
+ | `compile(ast, registry, location, pool)` | Returns lowered records, compile diagnostics and source maps. The baseline ignored pool; `pool` now holds other files' admitted records and resolves targets (S01) | [compiler](src/compile/compile.ts), [compile tests](tests/compile/compile.test.ts) |
25
23
  | Identity/path/taxonomy helpers | Explicit pure helpers and types; no location discovery | [identity tests](tests/identity.test.ts), [paths tests](tests/paths.test.ts), [taxonomy tests](tests/taxonomy.test.ts) |
26
24
 
27
25
  L04. A location supplies placement kind, authority band, reach and provenance. Bands are the closed set 100, 90, 50, 10 and 0. The package does not discover a filesystem location or decide graph reach/authority winners between compiled records.
28
26
 
29
- L05. The package exposes ESM runtime output and emitted TypeScript declarations. The `development` condition selects source; the ordinary package entry selects `dist/index.js`. [Smoke tests](tests/smoke.test.ts) pin public exports. Typechecking includes source and test projects.
27
+ L05. The package exposes ESM runtime output and emitted TypeScript declarations. In this repository the `development` condition selects source; the ordinary package entry selects `dist/index.js`. The published package exposes only `dist`: its exports carry no `development` condition. [Smoke tests](tests/smoke.test.ts) pin public exports. Typechecking includes source and test projects.
30
28
 
31
29
  ## 3. Surface and AST
32
30
 
@@ -66,7 +64,7 @@ Evidence: [system extraction](tests/registry/extract.test.ts), [field readers](t
66
64
 
67
65
  L19. A schema declares one closed lowered kind; section obligations terminate with exactly one open/closed marker; field obligations declare a section/key path, admitted type and optional description; edge obligations declare a verb, kind-or-discriminator target and cardinality. The verb may be any admitted relationship spelling, active (`govern`), inverse (`governed-by`) or present (`governs`, `grants access to`): the rule carries the active predicate, its direction relative to the record (`out` for the active and present spellings, `in` for the inverse) and the spelling as authored, so `may governed-by law one` obliges the edges whose active target is the record. Relationship fields are forbidden because edge obligations have their own dialect.
68
66
 
69
- L19a. A field type MAY carry one narrowing after it (W0, 2026-09-25): `id in [a, b]` and `list of id in [...]` declare a closed set of distinct bare ids (the row's value is the set, so it carries no description); `ref to <word>` and `list of ref to <word>` name the discriminator every reference must carry, without resolving it; `text form <form>` and `list of text form <form>` name a member of the closed text-form table `TEXT_FORMS`, whose only member is `iso-date`. A narrowing on another type, a second narrowing, an unknown form, an empty or duplicated set, and a non-id set member are `IA-LANG-SCHEMA-MALFORMED`; words after a set are parser-owned trailing values. The narrowing is stored beside the type as `values`, `target` or `form` on the field, and `fieldTypeText` spells it back. Checking a value against a narrowing is a compliance obligation (`IA-COMP-FIELD-VALUE`, `-FIELD-REF-TARGET`, `-FIELD-REF-MISSING`, `-FIELD-FORM`). Adding a text form changes the table and the compliance predicate, never the kernel.
67
+ L19a. A field type MAY carry one narrowing after it (2026-09-25): `id in [a, b]` and `list of id in [...]` declare a closed set of distinct bare ids (the row's value is the set, so it carries no description); `ref to <word>` and `list of ref to <word>` name the discriminator every reference must carry, without resolving it; `text form <form>` and `list of text form <form>` name a member of the closed text-form table `TEXT_FORMS`, whose only member is `iso-date`. A narrowing on another type, a second narrowing, an unknown form, an empty or duplicated set, and a non-id set member are `IA-LANG-SCHEMA-MALFORMED`; words after a set are parser-owned trailing values. The narrowing is stored beside the type as `values`, `target` or `form` on the field, and `fieldTypeText` spells it back. Checking a value against a narrowing is a compliance obligation (`IA-COMP-FIELD-VALUE`, `-FIELD-REF-TARGET`, `-FIELD-REF-MISSING`, `-FIELD-FORM`). Adding a text form changes the table and the compliance predicate, never the kernel.
70
68
 
71
69
  L20. A broken schema is refused whole. Duplicate declared sections, field paths or predicate/direction/target triples (a schema may state both `may govern law optional` and `may governed-by law optional`); malformed dialect rows; conditions; legacy prose dialect; wrong kinds/predicates; and unsupported row children are diagnosed by their own rules. Nested declarations own their faults separately.
72
70
 
@@ -158,23 +156,23 @@ Integration ownership: a schema with registry-owned conditions produces no seman
158
156
 
159
157
  ### Semantic delivery evidence
160
158
 
161
- Scope: reconciled against the baseline and the central dependency rules. S01–S12 specify the engineering decisions before source changes; the deliveries below implement and verify them.
159
+ These delivery paragraphs are historical and chronological: their test counts and their statements of remaining work describe their own checkpoint only. Scope: reconciled against the baseline and the central dependency rules. S01–S12 specify the engineering decisions before source changes; the deliveries below implement and verify them.
162
160
 
163
- Fragments and syntax ownership delivered: slash reference fragments in fields/lists/items; serializable syntax diagnostics; parser-tainted record/descendant refusal without duplicate reporting, including serialized nested ASTs; typed semantic products, retained generated-edge references and semantic source-map slots. Regression fixture expectations now include each ground edge's schema reference. Verified 529 tests in 25 files, typecheck and build. Semantic readers and pool resolution remain pending.
161
+ Fragments and syntax ownership delivered: slash reference fragments in fields/lists/items; serializable syntax diagnostics; parser-tainted record/descendant refusal without duplicate reporting, including serialized nested ASTs; typed semantic products, retained generated-edge references and semantic source-map slots. Regression fixture expectations now include each ground edge's schema reference. Verified 529 tests in 25 files, typecheck and build. Semantic readers and pool resolution were still pending.
164
162
 
165
- Value tables delivered: exact lane/shape/artifact-set values, shared canonical value lookup and all 54 active/inverse/present verb spellings with direction. New table tests cover every spelling, unknown/partial/case variants, literal/prototype-safe axis lookup and the retained five moves. Verified 575 tests in 26 files, typecheck and build. No runtime donor dependency was added.
163
+ Value tables delivered: exact lane/shape/artifact-set values, shared canonical value lookup and all 54 active/inverse/present verb spellings with direction. New table tests cover every spelling, unknown/partial/case variants, literal/prototype-safe axis lookup and the retained five moves. Verified 575 tests in 26 files, typecheck and build. No runtime dependency on the predecessor implementation was added.
166
164
 
167
- Conditions and selectors delivered: canonical terms and inline/direct-child conditions, independent selector groups, forbidden ordinary condition placement and explicit registry/nested-record ownership. Verified 646 tests in 29 files, typecheck and build. Reader integration and specialized carrier validation remain for later deliveries.
165
+ Conditions and selectors delivered: canonical terms and inline/direct-child conditions, independent selector groups, forbidden ordinary condition placement and explicit registry/nested-record ownership. Verified 646 tests in 29 files, typecheck and build. Reader integration and specialized carrier validation were left for later deliveries.
168
166
 
169
- Cells delivered: cognition cells with phase/primitive validation, primary and duplicate refusal boundaries, folded text, conditions and spans. Reviewed derived-error suppression with a failing regression before repair. Verified 683 tests/30 files, typecheck and build; compiler orchestration remains for the compiler integration.
167
+ Cells delivered: cognition cells with phase/primitive validation, primary and duplicate refusal boundaries, folded text, conditions and spans. Reviewed derived-error suppression with a failing regression before repair. Verified 683 tests/30 files, typecheck and build; compiler orchestration was left for the compiler integration.
170
168
 
171
- Resolver delivered: pure deterministic resolver and admitted-pool validation, preserving ambiguity and fragments without authority selection or fragment-existence checks. Verified 706 tests/31 files, typecheck and build. Compiler and graph consumers remain for their integrations.
169
+ Resolver delivered: pure deterministic resolver and admitted-pool validation, preserving ambiguity and fragments without authority selection or fragment-existence checks. Verified 706 tests/31 files, typecheck and build. Compiler and graph consumers were left for their integrations.
172
170
 
173
171
  Relationships delivered: typed relationship targets and conditions, warning retention, cardinality refusal, active-direction two-sided consent, generated-ground equivalence, and refused-binding intent for dependent validation. All 778 tests/32 files, typecheck/build pass. No graph resolution or execution is claimed.
174
172
 
175
173
  Governance variants delivered: governance variant families using schema-spelled keys and compiled values, normalized duplicate refusal, severity exclusion and no fallback from malformed conditions. Verified 793 tests/33 files, typecheck/build; coordinate overlap evaluation remains compliance-owned.
176
174
 
177
- Contracts and cases delivered: eight requirement clause kinds, whole-tree duplicate helper without a band exception, contract binding/retirement checks and case scenario/binding validation. Registry/dialect owners suppress derived and duplicate errors. Verified 882 tests/36 files, typecheck/build. Integration/local aggregation follows with the compiler integration; tree loading and compliance execution remain later components.
175
+ Contracts and cases delivered: eight requirement clause kinds, whole-tree duplicate helper without a band exception, contract binding/retirement checks and case scenario/binding validation. Registry/dialect owners suppress derived and duplicate errors. Verified 882 tests/36 files, typecheck/build. Integration/local aggregation followed with the compiler integration; tree loading and compliance execution were later components.
178
176
 
179
177
  Compiler integration delivered: the public compiler now produces every semantic array and parallel source map, resolves local/external references independently of source order, validates the external pool, filters local duplicate requirements and preserves diagnostic ownership. A complete case-contract-playbook chain compiles without errors. Verified 899 tests/37 files, typecheck/build. Conformance/public-surface closure and downstream handoff follow in section 11.
180
178
 
@@ -193,12 +191,12 @@ Conformance inputs: seven semantic fixture clauses run registry and compile. An
193
191
  | S08 open keys, severity metadata and normalized duplicates | semantic/variants and compiler integration | variants |
194
192
  | S09 clauses, tree duplicates and structural bindings | semantic/contracts, requirements, cases and a complete compiled chain | contracts, cases |
195
193
  | S10 scenario fields/kinds, verdict refusal and deferred execution | semantic/cases and compiler integration | cases |
196
- | S11 diagnostic codes, admitted-value messages and multiplicity | diagnostics inventory and explicit carrier/integration assertions | Every emitted code has a fail fixture; FORMAT-LOSSY remains reserved for the formatter (section 12) |
194
+ | S11 diagnostic codes, admitted-value messages and multiplicity | diagnostics inventory and explicit carrier/integration assertions | Every emitted code has a fail fixture; FORMAT-LOSSY, reserved at this checkpoint, is the formatter's (section 12) |
197
195
  | S12 structured previews and parallel surviving-product maps | compile integration and public type tests | All seven semantic pass clauses |
198
196
 
199
197
  At the semantic checkpoint, the package README mapped each product to an authored example and its then-future consumer. Those consumers have since shipped with their own tests; language tests alone do not establish their behavior. A registered 24-cell authoring playbook is compiled and resolved through the built package as a runtime API check, without claiming procedure execution.
200
198
 
201
- Conformance and public surface delivered: 89 semantic fixtures and a checked optional external-source pool format; public resolver/tree/vocabulary APIs; diagnostic/source ownership audit repairs; consumer mapping and published SPEC.md. Final verification: 995 tests/38 files, workspace typecheck/build, emitted-declaration consumer and built-runtime consumer. Every emitted code has a fixture; FORMAT-LOSSY is reserved until the formatter (section 12). Semantic compilation is complete, with kernel generation/migration, formatting and downstream consumers still assigned to later stages.
199
+ Conformance and public surface delivered: 89 semantic fixtures and a checked optional external-source pool format; public resolver/tree/vocabulary APIs; diagnostic/source ownership audit repairs; consumer mapping and published SPEC.md. Final verification: 995 tests/38 files, workspace typecheck/build, emitted-declaration consumer and built-runtime consumer. Every emitted code had a fixture; FORMAT-LOSSY was reserved until the formatter (section 12). Semantic compilation was complete; kernel generation/migration, formatting and downstream consumers came later (section 12 and the downstream packages).
202
200
 
203
201
  Scope-review correction to the semantic acceptance: interface, protocol and shape are retired registration keywords and receive KEYWORD-RESERVED. They do not become floor registrations. Three extraction regressions and three fail fixtures cover the correction. Verified 1001 tests/38 files, typecheck and build before migration.
204
202
 
@@ -212,7 +210,7 @@ P03. Formatter coverage includes every existing conformance source, strings/pros
212
210
 
213
211
  Formatter refinement before implementation: the preservation gate also compares logical-line depth/boundaries, so indentation cannot change record ownership while preserving lexical token values. Comment inventories include exact physical line and text; blank-line positions remain unchanged. The format conformance clause alone admits .formatted.txt (expected success output) and .candidate.txt (a deliberately changed candidate supplied to the public write guard); these files are not IA input extensions.
214
212
 
215
- Kernel generation delivered: 118 native floor records validate through language and compliance before deterministic embed generation. Closed constants and all 54 verb spellings now consume generated data; shape defaults, kind lanes, primitive anchors, dimension paths and digest are public. Root build checks output drift. Evidence: 1001 language tests, 62 compliance tests and 21 build-tool mutation/reproducibility tests, workspace and tool typecheck/build. Migration ran through the shared parser from seven hashed donor inputs; normal build has no donor dependency. Formatter and native five-system corpus remain pending.
213
+ Kernel generation delivered: 118 native floor records validate through language and compliance before deterministic embed generation. Closed constants and all 54 verb spellings now consume generated data; shape defaults, kind lanes, primitive anchors, dimension paths and digest are public. Root build checks output drift. Evidence: 1001 language tests, 62 compliance tests and 21 build-tool mutation/reproducibility tests, workspace and tool typecheck/build. Migration ran through the shared parser from seven hashed predecessor inputs; the normal build needs none of them. The formatter and the native five-system corpus were still pending at this checkpoint.
216
214
 
217
215
  Formatter delivered: pure scanner-driven format and preservation APIs, raw multiline/trivia retention, structural-depth guard and format conformance companions. Every conformance/native IA source is exercised for refusal or successful idempotence with unchanged parsed meaning. Verified 1241 language tests/39 files, 62 compliance tests and 40 tool tests, typecheck and build. Every emitted language code now has a fail fixture.
218
216
 
@@ -222,8 +220,10 @@ P04 (database bootstrap integration). Expose KERNEL_SOURCES, generated from the
222
220
 
223
221
  E01. Public `references(ast)` enumerates typed values, including head/list uses and qualified relationship targets, with enclosing record and authored span. It never interprets ordinary prose as references or turns typed uses into graph edges. The shared relationship target reader supplies qualified forms.
224
222
 
225
- E02. Public `/editor` projects the existing scanner and AST to zero-based UTF-16 positions, retaining BOM, CRLF and continuation indentation. Reference ranges distinguish multiple uses on one physical line. Cursor recovery is presentation-only and never changes parse/admission results. Unsupported versions yield no semantic suggestions. Comments, strings and prose suppress structural completion.
223
+ E02. Public `./editor` exports `projectSource(source, path)`, `cursorContext(source, path, at, projection?)`, `lineRange(source, span)`, `recordsIn(ast)` and `contains(range, at)`. They project the existing scanner and AST to zero-based UTF-16 positions, retaining BOM, CRLF and continuation indentation. Reference ranges distinguish multiple uses on one physical line. Cursor recovery is presentation-only and never changes parse/admission results. Unsupported versions yield no semantic suggestions. Comments, strings and prose suppress structural completion.
226
224
 
227
225
  E03. Editor formatting uses `format` and its preservation guard. Schema-guided new drafts serialize only supported typed values; unmodeled structures remain source-editable. No second lexer or parser is introduced in a host.
228
226
 
229
- E04. Schema-aware source edits (2026-10-11): `/editor` publishes `appendRecord(text, draft)`, `addRelationship(text, identity, spelling, target)` and `setField(text, identity, path, value, schema, append?)`, each returning the whole file again with exactly one top-level record (`@word name`) changed, and `annotateRecord(text, identity, comment)`, which puts one comment line above a record. The edit is spliced into the file as it is: every other line keeps its bytes, its line ending, comments and spacing included, a byte-order mark stays, and only the edited record is formatted (`format`), in the file's line ending, so only that record's digest can move. The file must parse; it need not be formatted. `encodeValue(field, text, item?)` spells one form value for a schema field: text is always quoted, and every other type must parse as exactly one value of it, by the predicates compliance applies (id and its `in` set, ref and its `to` word, qname, number, flag, list of one, and the iso-date form), with nothing after it; line breaks, C0 and C1 controls but the tab, DEL, the Unicode line and paragraph separators and the bidirectional controls are refused. That strict spelling is an opt-in (`setField` and the CLI's authoring verbs use it). `draftSource` keeps 2.0.0's spelling through `draftValue(field, text)`: text quoted, every other type written as given, refusing only a value that would add structure: a line break (a plain `Error`, as 2.0.0 threw), and, with `SourceEditError`, a `when` condition, a comment, or a string, prose or list the value opens and does not close, which 2.0.0 wrote into the draft (a bug fix). `draftValue` called alone refuses a line break with `SourceEditError` too. A refused edit throws `SourceEditError` with a closed `reason` (parse, identity, nested, field, value, repeated, duplicate, spelling, target, structure) and changes nothing: an undeclared field, a value of another type, a field, section or record stated twice, a relationship row the section already holds word for word (a row that differs only in spelling is left to admission), a duplicate list item or record, a conditional or structured field, a comment inside a multi-line value being replaced, a nested record, and an unknown verb or a target that is neither a canonical identity nor `@word name` (either with an optional fragment). A trailing comment on a one-line field being replaced is kept. `relationshipConsent(registry, word, spelling, target, fragment?)` judges one relationship row as admission's two-sided consent rule does and names the refusing side and the system registering that side's word. No diagnostic code is added: the caller compiles the result and reports the refusal.
227
+ E04. Schema-aware source edits (2026-10-11): `/editor` publishes `appendRecord(text, draft)`, `addRelationship(text, identity, spelling, target)` and `setField(text, identity, path, value, schema, append?)`, each returning the whole file again with exactly one top-level record (`@word name`) changed, and `annotateRecord(text, identity, comment)`, which puts one comment line above a record. It replaces a comment directly above the record that starts with the same first word, so an attribution is replaced, not stacked. The edit is spliced into the file as it is: every other line keeps its bytes, its line ending, comments and spacing included, a byte-order mark stays, and only the edited record is formatted (`format`), in the file's line ending, so only that record's digest can move. The file must parse; it need not be formatted. `encodeValue(field, text, item?)` spells one form value for a schema field: text is always quoted, and every other type must parse as exactly one value of it, by the predicates compliance applies (id and its `in` set, ref and its `to` word, qname, number, flag, list of one, and the iso-date form), with nothing after it; line breaks, C0 and C1 controls but the tab, DEL, the Unicode line and paragraph separators and the bidirectional controls are refused. That strict spelling is an opt-in (`setField` and the CLI's authoring verbs use it). `draftSource` keeps 2.0.0's spelling through `draftValue(field, text)`: text quoted, every other type written as given, refusing only a value that would add structure: a line break (a plain `Error`, as 2.0.0 threw), and, with `SourceEditError`, a `when` condition, a comment, or a string, prose or list the value opens and does not close, which 2.0.0 wrote into the draft (a bug fix). `draftValue` called alone refuses a line break with `SourceEditError` too. A refused edit throws `SourceEditError` with a closed `reason` (parse, identity, nested, field, value, repeated, duplicate, spelling, target, structure) and changes nothing: an undeclared field, a value of another type, a field, section or record stated twice, a relationship row the section already holds word for word (a row that differs only in spelling is left to admission), a duplicate list item or record, a conditional or structured field, a comment inside a multi-line value being replaced, a nested record, and an unknown verb or a target that is neither a canonical identity nor `@word name` (either with an optional fragment). A trailing comment on a one-line field being replaced is kept. `relationshipConsent(registry, word, spelling, target, fragment?)` judges one relationship row as admission's two-sided consent rule does and names the refusing side and the system registering that side's word. No diagnostic code is added: the caller compiles the result and reports the refusal.
228
+
229
+ Evidence: `tests/edit-source.test.ts` pins E04's sibling-byte preservation for set-field, relationship, append and annotation edits on mixed LF/CRLF files. The cases exercise either initial ending, a BOM, noncanonical spacing and a final record with or without a terminating newline; byte comparisons do not normalize the untouched text.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inventarch/language",
3
- "version": "3.1.1",
3
+ "version": "3.2.0",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",