@blue-labs/language 3.10.0 → 4.0.0-rc.0

package/README.md

@@ -7,7 +7,7 @@ Small, fast TypeScript runtime for the Blue Language: parse YAML/JSON into BlueN
 - **BlueNode graph**: single, list, map, typed values, metadata (name/description), `contracts`, and references by `blueId`.
 - **Preprocessing**: `blue:` directive (aliases, BlueId, or URL fetch with allow-list), inline-type mappings, implicit type inference for primitives.
 - **Resolution/Merge**: deterministic resolver with a pluggable MergingProcessor pipeline (value propagation, type checking, list/dict validators, metadata propagation, basic-type guard).
-- **BlueId**: canonical JSON → SHA-256 → Base58; sync/async, lists supported; CIDv1 conversion.
+- **BlueId**: semantic content identity via `Blue.calculateBlueId*`; low-level Section 8 hashing via `BlueIdCalculator`; spec-native list controls (`$previous`, `$pos`, `$empty`); CIDv1 conversion.
 - **Providers**: resolve by BlueId from memory, repositories or built-in bootstrap content; sequential composition.
 - **Zod mapping**: convert nodes to typed objects with schema extensions & Blue annotations; serialize objects back to Blue-shaped JSON.
 - **Limits & paths**: restrict extension/merge by path or depth; compose limits.
@@ -43,7 +43,7 @@ const node = blue.yamlToNode(yaml);
 // 3) Resolve (merge types/references), optionally with limits
 const resolved = blue.resolve(node, PathLimits.withMaxDepth(10));
 
-// 4) Compute BlueId
+// 4) Compute semantic BlueId
 const blueId = blue.calculateBlueIdSync(resolved);
 
 // 5) Map to a Zod schema (with annotations supported)
@@ -92,7 +92,7 @@ const json = blue.nodeToJson(node, {
 
 ### Core graph
 
-- `BlueNode` – node model (name, description, type, itemType, keyType, valueType, value, items, properties, blueId, blue directive).
+- `BlueNode` – node model (name, description, type, itemType, keyType, valueType, value, items, properties, reference `blueId`, blue directive).
 - `ResolvedBlueNode` – wrapper for resolved nodes; includes `getMinimalNode()` and `getMinimalBlueId()`.
 
 ### Entry point
@@ -101,16 +101,17 @@ const json = blue.nodeToJson(node, {
   - Parsing: `yamlToNode(_)/jsonValueToNode(_)` (+ async variants), which preprocess and normalize.
   - Preprocess: blue directive (`BlueDirectivePreprocessor`) + default pipeline (`Preprocessor`).
   - Resolve: `resolve(node, limits)` → `ResolvedBlueNode`.
-  - IDs: `calculateBlueId(_)/calculateBlueIdSync(_)`.
+  - IDs: `calculateBlueId(_)/calculateBlueIdSync(_)` for semantic BlueId.
   - Mapping: `nodeToJson(node, 'official'|'simple'|'original'|{ format, blueContext })`, `nodeToSchemaOutput(node, zod)`.
   - Type checks: `isTypeOf(node, zod)`, `isTypeOfNode(node, typeNode)`, `isTypeOfBlueId(node, blueId)`.
   - Type aliases: `getTypeAliasByBlueId(blueId)` (returns inline aliases like `Text` for core types and `Package/Type` for repository types, including historical `blueId` values resolved to current aliases; `undefined` for empty/unknown ids).
-  - Helpers: `extend(node, limits)`, `transform(node, fn)`, `reverse(node)`, `restoreInlineTypes(node)`.
+  - Helpers: `extend(node, limits)`, `transform(node, fn)`, `minimize(node)`, `reverse(node)` (deprecated alias), `restoreInlineTypes(node)`.
   - Config: URL fetch allow-list (`enablePreprocessingDirectivesFetchForDomains([...])`), global limits, repositories.
 
 ### Resolution & merge
 
 - `Merger` + `MergingProcessor` pipeline: value → types → lists/dicts → metadata → basic checks.
+- List overlays support `$previous` append anchors, positional `$pos` refinements, and `$empty` content elements. Legacy inherited-list marker forms are not emitted by minimization.
 - `createDefaultMergingProcessor()` exports the default pipeline.
 
 ### Providers
@@ -131,9 +132,27 @@ const json = blue.nodeToJson(node, {
 
 ### Blue IDs & CIDs
 
-- `BlueIdCalculator` (sync/async); `Base58Sha256Provider`.
+- `Blue.calculateBlueId*` computes semantic BlueId by resolving and minimizing.
+- `BlueIdCalculator` is the low-level Section 8 hasher for already prepared shapes.
 - `BlueIds` validator; `BlueIdToCid` and `CidToBlueId` converters.
 
+### Identity and storage terms
+
+- **official / wrapped**: spec representation using `value` and `items`.
+- **minimal overlay**: compact authoring/storage form that resolves back to the same semantic identity.
+- **resolved tree**: mutable runtime `ResolvedBlueNode` produced by `resolve()`.
+- **semantic BlueId**: public identity stable across equivalent authoring, resolved, and minimal forms.
+- **reference BlueId**: the document `blueId` field, exposed as `getReferenceBlueId()` / `setReferenceBlueId()` with legacy `getBlueId()` / `setBlueId()` aliases.
+
+Provider ingest is strict: mixed `blueId + payload` and single-document
+`blueId: this` / `blueId: this#k` inputs are rejected, while top-level document
+sets with indexed `this#k` references are stored under a cyclic `MASTER` BlueId
+and exposed as `MASTER#i` document identities. Supplied repository IDs must
+match computed IDs. `yamlToNode` and `jsonValueToNode` remain permissive parse
+APIs, while `BlueNode` input to `calculateBlueId*` is assumed to be already
+preprocessed/normalized. Spec-native list controls are supported in Phase 1K,
+and direct cyclic document-set identities are supported in Phase 2.
+
 ### Limits
 
 - `PathLimits`, `CompositeLimits`, and `NO_LIMITS`. Build from node shape or explicit patterns.
@@ -148,6 +167,8 @@ const json = blue.nodeToJson(node, {
 - `docs/resolve.md` – resolver & merging pipeline.
 - `docs/preprocessor.md` – blue directive, inference & mappings.
 - `docs/blue-id.md` – BlueId algorithm and APIs.
+- `docs/glossary.md` – identity, minimization, storage, and snapshot terminology.
+- `docs/adr/` – architecture decisions for semantic BlueId, minimal storage, snapshots, list controls, and direct cycles.
 - `docs/mapping.md` – Zod mapping and serialization.
 - `docs/architecture.md` – end-to-end architecture.
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { BlueNode, type UrlFetchStrategy, BlueIdCalculator, JsonCanonicalizer, BlueIdToCid, Base58Sha256Provider, TypeSchemaResolver, Blue, applyBlueNodePatch, type BlueNodePatch, BlueNodeTypeSchema, type BlueRepository, Limits, Nodes, BasicNodeProvider, NodeResolver, type MergingProcessor, Merger, MergingProcessors, } from './lib';
+export { BlueNode, type UrlFetchStrategy, BlueIdCalculator, JsonCanonicalizer, BlueIdToCid, Base58Sha256Provider, TypeSchemaResolver, Blue, applyBlueNodePatch, type BlueNodePatch, BlueNodeTypeSchema, type BlueRepository, Limits, Nodes, BasicNodeProvider, createNodeProvider, reindexRepositoryForSemanticStorage, SemanticIdentityService, NodeResolver, type MergingProcessor, Merger, MergingProcessors, } from './lib';
 export * as Properties from './lib/utils/Properties';
 export * from './schema';
 export * from './schema/annotations';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,oBAAoB,EACpB,kBAAkB,EAClB,IAAI,EACJ,kBAAkB,EAClB,KAAK,aAAa,EAClB,kBAAkB,EAClB,KAAK,cAAc,EACnB,MAAM,EACN,KAAK,EACL,iBAAiB,EAGjB,YAAY,EACZ,KAAK,gBAAgB,EACrB,MAAM,EACN,iBAAiB,GAClB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAC;AACrD,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,oBAAoB,EACpB,kBAAkB,EAClB,IAAI,EACJ,kBAAkB,EAClB,KAAK,aAAa,EAClB,kBAAkB,EAClB,KAAK,cAAc,EACnB,MAAM,EACN,KAAK,EACL,iBAAiB,EACjB,kBAAkB,EAClB,mCAAmC,EACnC,uBAAuB,EAGvB,YAAY,EACZ,KAAK,gBAAgB,EACrB,MAAM,EACN,iBAAiB,GAClB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAC;AACrD,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC"}