@_linked/core 2.34.0 → 2.36.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 2.36.0
+
+### Minor Changes
+
+- [#349](https://github.com/linked-fw/core/pull/349) [`c68a46a`](https://github.com/linked-fw/core/commit/c68a46acab79aa36ba0d5282f01af535ac5253b6) Thanks [@flyon](https://github.com/flyon)! - Add `sharedState(pkg, name, init)`, which keeps module state on `globalThis` under `Symbol.for('<pkg>:<name>')` so two copies of a module share it, and `brandLinkedError(Cls, pkg, name)` with `isLinkedError(err, Cls)`, which recognises an error thrown by another copy of its defining module, where `instanceof` does not.
+
+## 2.35.1
+
+### Patch Changes
+
+- [#350](https://github.com/linked-fw/core/pull/350) [`77a7b77`](https://github.com/linked-fw/core/commit/77a7b778fba33e91413e6037221b8db65544c405) Thanks [@flyon](https://github.com/flyon)! - Errors for a shape that does not resolve name the property that points at it, the shape that declares that property, and the active catalog: `Shape class not found for <Place> (property 'home' of '<Person>' points at it; catalog 'p1#main' does not hold it)`. The errors stay plain `Error`s (and `ShapeValidationError` for `validate`), now thrown as `UnresolvedShapeError` with `shapeIri`, `property`, `propertyIri`, `ownerShapeIri` and `catalog` fields. `fromJSON` no longer reads a relation's sub-fields against the parent shape when the relation's value shape does not resolve; it throws the same error.
+
+## 2.35.0
+
+### Minor Changes
+
+- [#343](https://github.com/linked-fw/core/pull/343) [`84ddff8`](https://github.com/linked-fw/core/commit/84ddff8fc91a773296461da6983237ba1a1f8c31) Thanks [@flyon](https://github.com/flyon)! - ShapeCatalog and withShapeCatalog: build and run queries against a catalog without registering it.
+  
+  `ShapeCatalog.from(shapes, {name})` builds an immutable set of shapes (core's six built-ins always included from core's code); `withShapeCatalog(catalog, fn)` makes it the shapes every registry accessor reads while `fn` runs. Builders, field sets and IRs capture the catalog and re-enter it when they are lowered, compiled or live-tracked later, so one shape IRI can mean different shapes in different catalogs at once. `fromJSON(json, {catalog})` decodes against a catalog; the wire format is unchanged. Registry caches are kept per catalog, and an app that never uses a catalog runs as before.
+  
+  `syncShapes` now also writes core's six built-in shapes (`Shape`, `NodeShape`, `PropertyShape`, `List`, `PathNode`, `PathList`) into the dataset, with the same hash skip as every other shape. The first sync after upgrading writes them once; after that a sync rewrites one only when its hash changes, which happens when processes on different core versions sync the same dataset (each rewrites the built-ins its version describes differently). Under `orphanScope: 'ownedNamespaces'` core's namespace is never pruned. A `ShapeCatalog` ignores built-in rows in its data and resolves the six from code.
+
 ## 2.34.0
 
 ### Minor Changes

package/README.md

@@ -1246,6 +1246,30 @@ import {lower} from '@_linked/core';
 const ir = lower(CreateBuilder.from(Person).set({name: 'Alice'}));
 ```
 
+### Shape catalogs — queries against shapes you do not register
+
+The shape registry holds one definition per IRI. A host serving several projects (or branches)
+that share shape IRIs with different properties resolves each query against a `ShapeCatalog`
+instead:
+
+```typescript
+import {ShapeCatalog, withShapeCatalog, fromJSON} from '@_linked/core';
+
+const branch = ShapeCatalog.from(nodeShapeWires, {name: 'project-1#main'}); // immutable
+const query = withShapeCatalog(branch, () =>
+  SelectBuilder.from('https://example.org/shape/Person').select(['name']),
+);
+await query; // lowers and compiles against `branch`, though the scope has closed
+
+const received = fromJSON(json, {catalog: branch}); // the wire never carries a catalog
+```
+
+A builder keeps the catalog it was made in (`catalogOf(query)`), through clones, `exists()`,
+`count()`, lowering, compile and live queries. Inside a scope every registry read sees the
+catalog's shapes plus core's six built-ins (always from code, though `syncShapes` writes them
+into every dataset); a class the catalog does not hold keeps resolving
+globally. See [runtime instances](./docs/architecture/runtime-instances.md#shape-catalogs).
+
 ### DSL-JSON — the standard query format
 
 Every Linked query — select **and** every mutation — has one canonical, language-neutral form:
@@ -1344,6 +1368,36 @@ await Team.update({members: {add: [{id: personId}]}}).for({id: teamId});
 - A dataset can report changes made elsewhere through the optional `IDataset.subscribeChanges(listener)`;
   `publishChange(event)` does the same from application code; `invalidate(Shape | {id} | query)` is the manual lever.
 
+## Shared state and error brands
+
+A framework module can be evaluated twice in one process (under `linked start`, once by Vite's SSR
+module runner and once by Node) or twice in a browser. Two conventions make that second copy harmless:
+
+- **Module state lives on `globalThis`.** A module-level value that more than one caller reads or writes
+  (a registry, a configured singleton, a static that callers assign) is kept with `sharedState`, under
+  `Symbol.for('<pkg>:<name>')`, so every copy reads and writes the same container:
+
+  ```ts
+  import {sharedState} from '@_linked/core';
+  const state = sharedState('@_linked/my-pkg', 'Mailer.state', () => ({provider: null as Provider | null}));
+  export function setProvider(p: Provider) { state.provider = p; }
+  ```
+
+- **Errors are matched by brand, not `instanceof`.** A framework error class is branded once with
+  `brandLinkedError(Cls, '<pkg>', '<ClassName>')`, and code that catches an error from another package
+  checks it with `isLinkedError(err, Cls)`. That matches an instance thrown by any copy of the defining
+  module, and a subclass instance against its base.
+
+  ```ts
+  export class StoreError extends Error {}
+  brandLinkedError(StoreError, '@_linked/my-pkg', 'StoreError');
+  // elsewhere
+  if (isLinkedError(err, StoreError)) { /* … */ }
+  ```
+
+The full convention, including what stays per copy and how React contexts are handled, is in
+[shared state and error brands](https://github.com/linked-fw/cli/blob/main/docs/architecture/shared-state-and-error-brands.md).
+
 ## TODO
 
 - Allow `preloadFor` to accept another query (not just a component).

package/lib/esm/index.d.ts

@@ -7,13 +7,17 @@ export { rdfList } from './shapes/List.js';
 export { serializePathToNodeData } from './shapes/serializePathToNodeData.js';
 export { Shape } from './shapes/Shape.js';
 export { validate, assertValid, ShapeValidationError } from './shapes/validation.js';
+export { UnresolvedShapeError, type UnresolvedShapeDetails } from './utils/unresolvedShape.js';
 export type { ValidationReport, ValidationResult, ValidationMode, ValidateOptions, ValidatableShape, } from './shapes/validation.js';
 export { LinkedStorage } from './utils/LinkedStorage.js';
+export { sharedState, sharedStateKey } from './utils/sharedState.js';
+export { brandLinkedError, isLinkedError, linkedErrorBrand } from './utils/linkedError.js';
 export { SelectBuilder, QueryBuilder } from './queries/QueryBuilder.js';
 export { lower } from './queries/lower.js';
 export type { LowerableQuery } from './queries/lower.js';
 export { fromJSON } from './queries/fromJSON.js';
-export type { QueryJSON } from './queries/fromJSON.js';
+export type { QueryJSON, FromJSONOptions } from './queries/fromJSON.js';
+export { ShapeCatalog, withShapeCatalog, getActiveShapeCatalog, catalogOf, shapeCatalogKey, } from './utils/ShapeCatalog.js';
 export { getQueryContext, setQueryContext, subscribeQueryContext, PendingQueryContext, UnresolvedContextError, } from './queries/QueryContext.js';
 export { subscribeQueryDispatch } from './queries/queryDispatch.js';
 export type { QueryDispatchEvent, QueryDispatchListener } from './queries/queryDispatch.js';

package/lib/esm/index.js

@@ -15,11 +15,17 @@ export { serializePathToNodeData } from './shapes/serializePathToNodeData.js';
 export { Shape } from './shapes/Shape.js';
 // SHACL-aligned validation of plain data objects against a shape.
 export { validate, assertValid, ShapeValidationError } from './shapes/validation.js';
+export { UnresolvedShapeError } from './utils/unresolvedShape.js';
 export { LinkedStorage } from './utils/LinkedStorage.js';
+// Conventions that make a second copy of a framework module harmless.
+export { sharedState, sharedStateKey } from './utils/sharedState.js';
+export { brandLinkedError, isLinkedError, linkedErrorBrand } from './utils/linkedError.js';
 // New dynamic query building API (Phase 2)
 export { SelectBuilder, QueryBuilder } from './queries/QueryBuilder.js';
 export { lower } from './queries/lower.js';
 export { fromJSON } from './queries/fromJSON.js';
+// Shape catalogs: resolve queries against a set of shapes without registering them.
+export { ShapeCatalog, withShapeCatalog, getActiveShapeCatalog, catalogOf, shapeCatalogKey, } from './utils/ShapeCatalog.js';
 export { getQueryContext, setQueryContext, subscribeQueryContext, PendingQueryContext, UnresolvedContextError, } from './queries/QueryContext.js';
 export { subscribeQueryDispatch } from './queries/queryDispatch.js';
 export { CONTEXT_REF_KEY, encodeContextRef, isContextRefJSON, resolveContextId, } from './queries/ContextRef.js';

package/lib/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,0DAA0D;AAC1D,OAAO,mBAAmB,CAAC;AAC3B,8EAA8E;AAC9E,OAAO,WAAW,CAAC;AACnB,OAAO,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,wBAAwB,CAAC;AAE7D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,OAAO,EAAC,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAC,uBAAuB,EAAC,MAAM,qCAAqC,CAAC;AAC5E,sEAAsE;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,mBAAmB,CAAC;AACxC,kEAAkE;AAClE,OAAO,EAAC,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAQnF,OAAO,EAAC,aAAa,EAAC,MAAM,0BAA0B,CAAC;AACvD,2CAA2C;AAC3C,OAAO,EAAC,aAAa,EAAE,YAAY,EAAC,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,oBAAoB,CAAC;AAEzC,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAE/C,OAAO,EACL,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAElE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,YAAY,EAAE,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AAEzE,sBAAsB;AACtB,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAM/C,+BAA+B;AAC/B,OAAO,EAAC,UAAU,EAAE,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG/D,OAAO,EAAC,YAAY,EAAE,YAAY,EAAC,MAAM,2BAA2B,CAAC;AAGrE,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AAGzD,8CAA8C;AAC9C,OAAO,EAAC,cAAc,EAAC,MAAM,iCAAiC,CAAC;AAE/D,OAAO,EAAC,IAAI,EAAC,MAAM,uBAAuB,CAAC;AAe3C,sEAAsE;AACtE,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,iBAAiB,GAClB,MAAM,gCAAgC,CAAC;AAWxC,0FAA0F;AAC1F,OAAO,EAAC,iBAAiB,EAAE,eAAe,EAAC,MAAM,gCAAgC,CAAC;AAElF,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAEhE,mDAAmD;AACnD,OAAO,EAAC,cAAc,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,aAAa,EAAE,UAAU,EAAC,MAAM,0BAA0B,CAAC","sourcesContent":["/*\n * This Source Code Form is subject to the terms of the Mozilla Public\n * License, v. 2.0. If a copy of the MPL was not distributed with this\n * file, You can obtain one at https://mozilla.org/MPL/2.0/.\n */\n// Registers every shape core defines (side effects only).\nimport './shapes/index.js';\n// Registers the live-query store so `query.live()` works (side effects only).\nimport './live.js';\nexport {syncShapes, syncShape} from './shapes/syncShapes.js';\nexport type {SyncShapesOptions, SyncShapeOptions} from './shapes/syncShapes.js';\nexport {\n  singleOwnerShapeIri,\n  singleOwnerProperties,\n  buildSingleOwnerConstraints,\n} from './shapes/singleOwnerConstraint.js';\nexport {rdfList} from './shapes/List.js';\nexport {serializePathToNodeData} from './shapes/serializePathToNodeData.js';\n// Core public API surface (documented as root imports in the README).\nexport {Shape} from './shapes/Shape.js';\n// SHACL-aligned validation of plain data objects against a shape.\nexport {validate, assertValid, ShapeValidationError} from './shapes/validation.js';\nexport type {\n  ValidationReport,\n  ValidationResult,\n  ValidationMode,\n  ValidateOptions,\n  ValidatableShape,\n} from './shapes/validation.js';\nexport {LinkedStorage} from './utils/LinkedStorage.js';\n// New dynamic query building API (Phase 2)\nexport {SelectBuilder, QueryBuilder} from './queries/QueryBuilder.js';\nexport {lower} from './queries/lower.js';\nexport type {LowerableQuery} from './queries/lower.js';\nexport {fromJSON} from './queries/fromJSON.js';\nexport type {QueryJSON} from './queries/fromJSON.js';\nexport {\n  getQueryContext,\n  setQueryContext,\n  subscribeQueryContext,\n  PendingQueryContext,\n  UnresolvedContextError,\n} from './queries/QueryContext.js';\nexport {subscribeQueryDispatch} from './queries/queryDispatch.js';\nexport type {QueryDispatchEvent, QueryDispatchListener} from './queries/queryDispatch.js';\nexport {\n  CONTEXT_REF_KEY,\n  encodeContextRef,\n  isContextRefJSON,\n  resolveContextId,\n} from './queries/ContextRef.js';\nexport type {ContextRefJSON} from './queries/ContextRef.js';\nexport {PropertyPath, walkPropertyPath} from './queries/PropertyPath.js';\n\n// Phase 3a — FieldSet\nexport {FieldSet} from './queries/FieldSet.js';\nexport type {FieldSetEntry, FieldSetInput, FieldSetJSON, FieldSetFieldJSON} from './queries/FieldSet.js';\n\n// Phase 4 — Serialization types\nexport type {QueryBuilderJSON} from './queries/QueryBuilder.js';\n\n// Phase 3b — Mutation builders\nexport {AskBuilder, isAskQuery} from './queries/AskBuilder.js';\nexport type {AskSpec} from './queries/AskBuilder.js';\nexport type {AskQuery, AskQueryJSON, RawAskInput} from './queries/AskQuery.js';\nexport {CountBuilder, isCountQuery} from './queries/CountBuilder.js';\nexport type {CountSpec} from './queries/CountBuilder.js';\nexport type {CountQuery, CountQueryJSON, RawCountInput} from './queries/CountQuery.js';\nexport {CreateBuilder} from './queries/CreateBuilder.js';\nexport {UpdateBuilder} from './queries/UpdateBuilder.js';\nexport {DeleteBuilder} from './queries/DeleteBuilder.js';\nexport type {DeleteId} from './queries/DeleteBuilder.js';\n\n// Expressions — computed fields and functions\nexport {ExpressionNode} from './expressions/ExpressionNode.js';\nexport type {ExpressionInput, PropertyRefMap} from './expressions/ExpressionNode.js';\nexport {Expr} from './expressions/Expr.js';\nexport type {\n  ExpressionUpdateProxy,\n  ExpressionUpdateResult,\n  BaseExpressionMethods,\n  NumericExpressionMethods,\n  StringExpressionMethods,\n  DateExpressionMethods,\n  BooleanExpressionMethods,\n} from './expressions/ExpressionMethods.js';\n\n// Phase 5 — Component query integration\nexport type {LinkedComponentInterface, QueryComponentLike} from './queries/SelectQuery.js';\n\n\n// Mutation DSL-JSON serialization (create/update/delete to/from JSON)\nexport {\n  encodeNodeData,\n  encodeValue,\n} from './queries/MutationSerialization.js';\nexport {\n  decodeNodeData,\n  lowerMutationJSON,\n} from './queries/lowerMutationJSON.js';\nexport type {\n  MutationJSON,\n  CreateMutationJSON,\n  UpdateMutationJSON,\n  DeleteMutationJSON,\n  MutationValueJSON,\n  MutationNodeDataJSON,\n} from './queries/MutationSerialization.js';\n\n\n// Live-query dependency helpers — what a query reads and a mutation writes, as predicates\nexport {queryDependencies, mutationEffects} from './queries/queryDependencies.js';\nexport type {QueryDependencies, MutationEffects} from './queries/queryDependencies.js';\nexport {findPropertyShapeById} from './shapes/nodeShapeData.js';\n\n// Live queries — see documentation/live-queries.md\nexport {LiveQueryStore, getLiveQueryStore, resetLiveQueryStore, publishChange, invalidate} from './live/LiveQueryStore.js';\nexport type {ChangeEvent} from './live/changes.js';\nexport type {\n  LiveQuery,\n  LiveState,\n  LiveStatus,\n  LiveListener,\n  LiveQueryOptions,\n  LiveQueryStoreOptions,\n} from './live/LiveQueryStore.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,0DAA0D;AAC1D,OAAO,mBAAmB,CAAC;AAC3B,8EAA8E;AAC9E,OAAO,WAAW,CAAC;AACnB,OAAO,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,wBAAwB,CAAC;AAE7D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,OAAO,EAAC,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAC,uBAAuB,EAAC,MAAM,qCAAqC,CAAC;AAC5E,sEAAsE;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,mBAAmB,CAAC;AACxC,kEAAkE;AAClE,OAAO,EAAC,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACnF,OAAO,EAAC,oBAAoB,EAA8B,MAAM,4BAA4B,CAAC;AAQ7F,OAAO,EAAC,aAAa,EAAC,MAAM,0BAA0B,CAAC;AACvD,sEAAsE;AACtE,OAAO,EAAC,WAAW,EAAE,cAAc,EAAC,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAC,gBAAgB,EAAE,aAAa,EAAE,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AACzF,2CAA2C;AAC3C,OAAO,EAAC,aAAa,EAAE,YAAY,EAAC,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,oBAAoB,CAAC;AAEzC,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAE/C,oFAAoF;AACpF,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,SAAS,EACT,eAAe,GAChB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAElE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,YAAY,EAAE,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AAEzE,sBAAsB;AACtB,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAM/C,+BAA+B;AAC/B,OAAO,EAAC,UAAU,EAAE,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG/D,OAAO,EAAC,YAAY,EAAE,YAAY,EAAC,MAAM,2BAA2B,CAAC;AAGrE,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AAGzD,8CAA8C;AAC9C,OAAO,EAAC,cAAc,EAAC,MAAM,iCAAiC,CAAC;AAE/D,OAAO,EAAC,IAAI,EAAC,MAAM,uBAAuB,CAAC;AAe3C,sEAAsE;AACtE,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,iBAAiB,GAClB,MAAM,gCAAgC,CAAC;AAWxC,0FAA0F;AAC1F,OAAO,EAAC,iBAAiB,EAAE,eAAe,EAAC,MAAM,gCAAgC,CAAC;AAElF,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAEhE,mDAAmD;AACnD,OAAO,EAAC,cAAc,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,aAAa,EAAE,UAAU,EAAC,MAAM,0BAA0B,CAAC","sourcesContent":["/*\n * This Source Code Form is subject to the terms of the Mozilla Public\n * License, v. 2.0. If a copy of the MPL was not distributed with this\n * file, You can obtain one at https://mozilla.org/MPL/2.0/.\n */\n// Registers every shape core defines (side effects only).\nimport './shapes/index.js';\n// Registers the live-query store so `query.live()` works (side effects only).\nimport './live.js';\nexport {syncShapes, syncShape} from './shapes/syncShapes.js';\nexport type {SyncShapesOptions, SyncShapeOptions} from './shapes/syncShapes.js';\nexport {\n  singleOwnerShapeIri,\n  singleOwnerProperties,\n  buildSingleOwnerConstraints,\n} from './shapes/singleOwnerConstraint.js';\nexport {rdfList} from './shapes/List.js';\nexport {serializePathToNodeData} from './shapes/serializePathToNodeData.js';\n// Core public API surface (documented as root imports in the README).\nexport {Shape} from './shapes/Shape.js';\n// SHACL-aligned validation of plain data objects against a shape.\nexport {validate, assertValid, ShapeValidationError} from './shapes/validation.js';\nexport {UnresolvedShapeError, type UnresolvedShapeDetails} from './utils/unresolvedShape.js';\nexport type {\n  ValidationReport,\n  ValidationResult,\n  ValidationMode,\n  ValidateOptions,\n  ValidatableShape,\n} from './shapes/validation.js';\nexport {LinkedStorage} from './utils/LinkedStorage.js';\n// Conventions that make a second copy of a framework module harmless.\nexport {sharedState, sharedStateKey} from './utils/sharedState.js';\nexport {brandLinkedError, isLinkedError, linkedErrorBrand} from './utils/linkedError.js';\n// New dynamic query building API (Phase 2)\nexport {SelectBuilder, QueryBuilder} from './queries/QueryBuilder.js';\nexport {lower} from './queries/lower.js';\nexport type {LowerableQuery} from './queries/lower.js';\nexport {fromJSON} from './queries/fromJSON.js';\nexport type {QueryJSON, FromJSONOptions} from './queries/fromJSON.js';\n// Shape catalogs: resolve queries against a set of shapes without registering them.\nexport {\n  ShapeCatalog,\n  withShapeCatalog,\n  getActiveShapeCatalog,\n  catalogOf,\n  shapeCatalogKey,\n} from './utils/ShapeCatalog.js';\nexport {\n  getQueryContext,\n  setQueryContext,\n  subscribeQueryContext,\n  PendingQueryContext,\n  UnresolvedContextError,\n} from './queries/QueryContext.js';\nexport {subscribeQueryDispatch} from './queries/queryDispatch.js';\nexport type {QueryDispatchEvent, QueryDispatchListener} from './queries/queryDispatch.js';\nexport {\n  CONTEXT_REF_KEY,\n  encodeContextRef,\n  isContextRefJSON,\n  resolveContextId,\n} from './queries/ContextRef.js';\nexport type {ContextRefJSON} from './queries/ContextRef.js';\nexport {PropertyPath, walkPropertyPath} from './queries/PropertyPath.js';\n\n// Phase 3a — FieldSet\nexport {FieldSet} from './queries/FieldSet.js';\nexport type {FieldSetEntry, FieldSetInput, FieldSetJSON, FieldSetFieldJSON} from './queries/FieldSet.js';\n\n// Phase 4 — Serialization types\nexport type {QueryBuilderJSON} from './queries/QueryBuilder.js';\n\n// Phase 3b — Mutation builders\nexport {AskBuilder, isAskQuery} from './queries/AskBuilder.js';\nexport type {AskSpec} from './queries/AskBuilder.js';\nexport type {AskQuery, AskQueryJSON, RawAskInput} from './queries/AskQuery.js';\nexport {CountBuilder, isCountQuery} from './queries/CountBuilder.js';\nexport type {CountSpec} from './queries/CountBuilder.js';\nexport type {CountQuery, CountQueryJSON, RawCountInput} from './queries/CountQuery.js';\nexport {CreateBuilder} from './queries/CreateBuilder.js';\nexport {UpdateBuilder} from './queries/UpdateBuilder.js';\nexport {DeleteBuilder} from './queries/DeleteBuilder.js';\nexport type {DeleteId} from './queries/DeleteBuilder.js';\n\n// Expressions — computed fields and functions\nexport {ExpressionNode} from './expressions/ExpressionNode.js';\nexport type {ExpressionInput, PropertyRefMap} from './expressions/ExpressionNode.js';\nexport {Expr} from './expressions/Expr.js';\nexport type {\n  ExpressionUpdateProxy,\n  ExpressionUpdateResult,\n  BaseExpressionMethods,\n  NumericExpressionMethods,\n  StringExpressionMethods,\n  DateExpressionMethods,\n  BooleanExpressionMethods,\n} from './expressions/ExpressionMethods.js';\n\n// Phase 5 — Component query integration\nexport type {LinkedComponentInterface, QueryComponentLike} from './queries/SelectQuery.js';\n\n\n// Mutation DSL-JSON serialization (create/update/delete to/from JSON)\nexport {\n  encodeNodeData,\n  encodeValue,\n} from './queries/MutationSerialization.js';\nexport {\n  decodeNodeData,\n  lowerMutationJSON,\n} from './queries/lowerMutationJSON.js';\nexport type {\n  MutationJSON,\n  CreateMutationJSON,\n  UpdateMutationJSON,\n  DeleteMutationJSON,\n  MutationValueJSON,\n  MutationNodeDataJSON,\n} from './queries/MutationSerialization.js';\n\n\n// Live-query dependency helpers — what a query reads and a mutation writes, as predicates\nexport {queryDependencies, mutationEffects} from './queries/queryDependencies.js';\nexport type {QueryDependencies, MutationEffects} from './queries/queryDependencies.js';\nexport {findPropertyShapeById} from './shapes/nodeShapeData.js';\n\n// Live queries — see documentation/live-queries.md\nexport {LiveQueryStore, getLiveQueryStore, resetLiveQueryStore, publishChange, invalidate} from './live/LiveQueryStore.js';\nexport type {ChangeEvent} from './live/changes.js';\nexport type {\n  LiveQuery,\n  LiveState,\n  LiveStatus,\n  LiveListener,\n  LiveQueryOptions,\n  LiveQueryStoreOptions,\n} from './live/LiveQueryStore.js';\n"]}

package/lib/esm/live/LiveQueryStore.d.ts

@@ -1,4 +1,5 @@
 import { type MutationEffects, type QueryDependencies } from '../queries/queryDependencies.js';
+import type { ShapeCatalog } from '../utils/ShapeCatalog.js';
 import type { ShapeConstructor } from '../shapes/Shape.js';
 import { type ChangeEvent, type ChangeOrigin } from './changes.js';
 import { type InstanceParams, type LiveBuilder, type LiveQueryKind } from './keys.js';
@@ -64,6 +65,11 @@ export interface LiveQuery<R = unknown> extends PromiseLike<R> {
 export type Template = {
     key: string;
     kind: LiveQueryKind;
+    /**
+     * The catalog the template's queries resolve in (undefined = the global registry). Part
+     * of its identity: the same JSON in two catalogs is two templates.
+     */
+    catalog?: ShapeCatalog;
     name?: string;
     json: Record<string, unknown>;
     /** Subject-stripped builder, used for dependency analysis only. */
@@ -124,6 +130,8 @@ export declare class LiveQueryStore {
     private readonly _recentChanges;
     private _pendingRefetch;
     private _flushScheduled;
+    /** How many templates each catalog has; a change is decoded once per catalog listed here. */
+    private readonly _catalogTemplates;
     constructor();
     /** Register (or find) the template of `query`. Options merge into an existing template. */
     template(query: LiveBuilder, opts?: LiveQueryOptions): Template;
@@ -190,6 +198,19 @@ export declare class LiveQueryStore {
      * in quick succession are two changes — and manual invalidations never are.
      */
     publish(event: ChangeEvent, origin?: ChangeOrigin): void;
+    /**
+     * `within` limits the change to one catalog's templates (undefined = the global registry's):
+     * a local mutation changes the data of the catalog it was made in, and only that one.
+     */
+    private _publish;
+    /**
+     * The effects of a change in the global registry and in each catalog that has
+     * templates. A mutation is decoded once per catalog; one that does not resolve in a
+     * catalog (its shape is not there) leaves that catalog's templates alone, and effects
+     * given as data apply to a catalog only when it holds their shape. Throws only when
+     * the change resolves nowhere, as a change that cannot be decoded did before catalogs.
+     */
+    private _decodePerCatalog;
     private _scheduleFlush;
     /**
      * Local mutations. Select and ask events are ignored: the store's own fetches
@@ -220,6 +241,7 @@ export declare class LiveQueryStore {
     private _onContextChange;
     /** Remove an instance from its template (and the template when it is empty and not pinned). */
     private _dropInstance;
+    private _forgetCatalogTemplate;
     private _scheduleGc;
     private _cancelGc;
 }

package/lib/esm/live/LiveQueryStore.js

@@ -17,11 +17,12 @@ import { subscribeQueryContext, UnresolvedContextError } from '../queries/QueryC
 import { resolveContextId } from '../queries/ContextRef.js';
 import { subscribeQueryDispatch } from '../queries/queryDispatch.js';
 import { mutationEffects, queryDependencies, } from '../queries/queryDependencies.js';
-import { getShapeClass } from '../utils/ShapeClass.js';
+import { catalogOf, getActiveShapeCatalog, getShapeClass, withShapeCatalog, } from '../utils/ShapeClass.js';
 import { effectsHash, normalizeChange } from './changes.js';
 import { selectInstances } from './matcher.js';
-import { kindOf, paramsKey, splitQuery, stableStringify, stripSubjects, } from './keys.js';
+import { kindOf, paramsKey, splitQuery, stripSubjects, templateKeyFor, } from './keys.js';
 import { setLiveQueryStore, peekLiveQueryStore } from './registry.js';
+import { isLinkedError } from '../utils/linkedError.js';
 const IDLE = Object.freeze({ status: 'pending', notFound: false, refreshing: false });
 // ---------------------------------------------------------------------------
 // Store
@@ -48,6 +49,8 @@ export class LiveQueryStore {
         this._recentChanges = new Map();
         this._pendingRefetch = new Set();
         this._flushScheduled = false;
+        /** How many templates each catalog has; a change is decoded once per catalog listed here. */
+        this._catalogTemplates = new Map();
         this._disposers.push(subscribeQueryContext((name) => this._onContextChange(name)));
         this._disposers.push(subscribeQueryDispatch((e) => this._onDispatch(e)));
         this._disposers.push(LinkedStorage.onRoutingChanged(() => this._onRoutingChanged()));
@@ -61,20 +64,16 @@ export class LiveQueryStore {
         return this._template(splitQuery(query).templateJson, query, opts);
     }
     _template(templateJson, query, opts) {
-        const key = stableStringify(templateJson);
+        var _a;
+        const catalog = catalogOf(query);
+        const key = templateKeyFor(templateJson, catalog);
         let t = this._templates.get(key);
         if (!t) {
-            t = {
-                key,
-                kind: kindOf(query),
-                json: templateJson,
-                builder: stripSubjects(query),
-                shapeIri: typeof templateJson.shape === 'string' ? templateJson.shape : undefined,
-                reactive: true,
-                pinned: false,
-                instances: new Map(),
-            };
+            t = Object.assign(Object.assign({ key, kind: kindOf(query) }, (catalog !== undefined ? { catalog } : {})), { json: templateJson, builder: stripSubjects(query), shapeIri: typeof templateJson.shape === 'string' ? templateJson.shape : undefined, reactive: true, pinned: false, instances: new Map() });
             this._templates.set(key, t);
+            if (catalog !== undefined) {
+                this._catalogTemplates.set(catalog, ((_a = this._catalogTemplates.get(catalog)) !== null && _a !== void 0 ? _a : 0) + 1);
+            }
         }
         if (opts.name !== undefined)
             t.name = opts.name;
@@ -107,7 +106,7 @@ export class LiveQueryStore {
             template.depsProvisional = false;
         }
         catch (err) {
-            if (!(err instanceof UnresolvedContextError))
+            if (!isLinkedError(err, UnresolvedContextError))
                 throw err;
             if (template.deps)
                 return template.deps; // still provisional
@@ -245,7 +244,7 @@ export class LiveQueryStore {
                 instances.add(i);
         }
         else if (typeof target.__queryKind === 'string') {
-            const t = this._templates.get(stableStringify(splitQuery(target).templateJson));
+            const t = this._templates.get(templateKeyFor(splitQuery(target).templateJson, catalogOf(target)));
             if (t)
                 for (const i of t.instances.values())
                     instances.add(i);
@@ -281,7 +280,17 @@ export class LiveQueryStore {
      * in quick succession are two changes — and manual invalidations never are.
      */
     publish(event, origin = 'app') {
-        const effects = normalizeChange(event);
+        this._publish(event, origin);
+    }
+    /**
+     * `within` limits the change to one catalog's templates (undefined = the global registry's):
+     * a local mutation changes the data of the catalog it was made in, and only that one.
+     */
+    _publish(event, origin, within) {
+        const decoded = within
+            ? [[within.catalog, normalizeChange(event, { catalog: within.catalog })]]
+            : this._decodePerCatalog(event);
+        const effects = decoded[0][1];
         if (origin !== 'manual') {
             const hash = effectsHash(effects);
             const now = Date.now();
@@ -297,10 +306,52 @@ export class LiveQueryStore {
                         this._recentChanges.delete(h);
             }
         }
-        for (const inst of selectInstances(this, effects))
-            this._pendingRefetch.add(inst);
+        if (decoded.length === 1 && decoded[0][0] === undefined && this._catalogTemplates.size === 0) {
+            for (const inst of selectInstances(this, effects))
+                this._pendingRefetch.add(inst);
+        }
+        else {
+            for (const [catalog, e] of decoded) {
+                for (const inst of selectInstances(this, e, { catalog }))
+                    this._pendingRefetch.add(inst);
+            }
+        }
         this._scheduleFlush();
     }
+    /**
+     * The effects of a change in the global registry and in each catalog that has
+     * templates. A mutation is decoded once per catalog; one that does not resolve in a
+     * catalog (its shape is not there) leaves that catalog's templates alone, and effects
+     * given as data apply to a catalog only when it holds their shape. Throws only when
+     * the change resolves nowhere, as a change that cannot be decoded did before catalogs.
+     */
+    _decodePerCatalog(event) {
+        if (this._catalogTemplates.size === 0) {
+            return [[undefined, normalizeChange(event, { catalog: undefined })]];
+        }
+        const out = [];
+        let globalError;
+        try {
+            out.push([undefined, normalizeChange(event, { catalog: undefined })]);
+        }
+        catch (err) {
+            globalError = err;
+        }
+        for (const catalog of this._catalogTemplates.keys()) {
+            try {
+                const effects = normalizeChange(event, { catalog });
+                if ('effects' in event && !catalog.has(effects.shape))
+                    continue;
+                out.push([catalog, effects]);
+            }
+            catch (_a) {
+                // Not a change to this catalog's shapes.
+            }
+        }
+        if (out.length === 0)
+            throw globalError;
+        return out;
+    }
     _scheduleFlush() {
         if (this._flushScheduled)
             return;
@@ -321,7 +372,12 @@ export class LiveQueryStore {
         if (e.kind !== 'create' && e.kind !== 'update' && e.kind !== 'delete')
             return;
         const query = e.query;
-        const dataset = (_a = e.target) !== null && _a !== void 0 ? _a : LinkedStorage.getDatasetForShapeClass((((_b = query.shape) === null || _b === void 0 ? void 0 : _b.id) ? getShapeClass(query.shape.id) : undefined));
+        // The routing lookup reads the registry, so it runs in the mutation's catalog.
+        const catalog = catalogOf(query);
+        const shapeClassOf = (id) => catalog === getActiveShapeCatalog()
+            ? getShapeClass(id)
+            : withShapeCatalog(catalog, () => getShapeClass(id));
+        const dataset = (_a = e.target) !== null && _a !== void 0 ? _a : LinkedStorage.getDatasetForShapeClass((((_b = query.shape) === null || _b === void 0 ? void 0 : _b.id) ? shapeClassOf(query.shape.id) : undefined));
         if (dataset === null || dataset === void 0 ? void 0 : dataset.authoritativeChanges)
             return; // the dataset's own feed will report it
         e.result.then((result) => {
@@ -333,7 +389,7 @@ export class LiveQueryStore {
                 console.error('[linked] could not derive the effects of a mutation; live queries were not refetched', err);
                 return;
             }
-            this.publish({ effects }, 'local');
+            this._publish({ effects }, 'local', { catalog });
         }, () => { });
     }
     /** Subscribe to the change feeds of the datasets currently routed; drop feeds of datasets that left. */
@@ -383,6 +439,7 @@ export class LiveQueryStore {
                 this._dropInstance(i, true);
         }
         this._templates.clear();
+        this._catalogTemplates.clear();
         this.templatesByProp.clear();
         this.templatesByShape.clear();
         this.instancesById.clear();
@@ -548,8 +605,19 @@ export class LiveQueryStore {
         if (!keepTemplate && t.instances.size === 0 && !t.pinned) {
             this._templates.delete(t.key);
             this._unindexTemplate(t);
+            this._forgetCatalogTemplate(t);
         }
     }
+    _forgetCatalogTemplate(t) {
+        var _a;
+        if (t.catalog === undefined)
+            return;
+        const left = ((_a = this._catalogTemplates.get(t.catalog)) !== null && _a !== void 0 ? _a : 1) - 1;
+        if (left > 0)
+            this._catalogTemplates.set(t.catalog, left);
+        else
+            this._catalogTemplates.delete(t.catalog);
+    }
     _scheduleGc(inst) {
         var _a, _b;
         this._cancelGc(inst);