@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 +2 -2
- package/README.md +8 -4
- package/SPEC.md +19 -19
- 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/language
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/@inventarch/language) [](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml) [](LICENSE) [](https://www.npmjs.com/package/@inventarch/language) [](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml) [](LICENSE) [](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)` |
|
|
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
|
-
|
|
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
|
|
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
|
|
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.
|
|
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 (
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|