@_linked/core 2.31.0 → 2.33.0

package/lib/esm/shapes/singleOwnerConstraint.js

@@ -6,12 +6,18 @@
 import { getPropertyShapes } from './nodeShapeData.js';
 import { getSimplePathId } from '../paths/normalizePropertyPath.js';
 import { serializePathToNodeData } from './serializePathToNodeData.js';
+import { getSubShapes } from '../utils/ShapeClass.js';
+import { NodeShape } from './SHACL.js';
+import { PathList } from './PathList.js';
+import { rdf } from '../ontologies/rdf.js';
 /**
  * The single-owner SHACL constraints generated from `contains` properties.
  *
- * A `contains` property says the subject owns the value node. For every such property, shape
- * sync writes one generated NodeShape stating the matching store-side rule: every object of the
- * property's predicate has at most one subject pointing at it through that predicate.
+ * A `contains` property says the subject owns the value node, and only that property does: a
+ * plain property on the same predicate is a reference. For every such property, shape sync
+ * writes one generated NodeShape stating the matching store-side rule: every object of the
+ * property's predicate has at most one subject pointing at it through that predicate *that is
+ * an instance of the declaring class or of a registered sub-shape's class*.
  *
  * ```turtle
  * <…/Thing/image.singleOwner> a sh:NodeShape ;
@@ -19,19 +25,26 @@ import { serializePathToNodeData } from './serializePathToNodeData.js';
  *     sh:targetObjectsOf schema:image ;
  *     sh:property <…/Thing/image.singleOwner/owners> .
  * <…/Thing/image.singleOwner/owners> a sh:PropertyShape ;
- *     sh:maxCount 1 ;
- *     sh:path [ sh:inversePath schema:image ] .
+ *     sh:path [ sh:inversePath schema:image ] ;
+ *     sh:qualifiedValueShape [ sh:or ( [ sh:class schema:Thing ] [ sh:class ex:Project ] ) ] ;
+ *     sh:qualifiedMaxCount 1 .
  * ```
  *
+ * The owner classes are enumerated rather than left to `sh:class` alone, because `sh:class`
+ * matches a subclass instance only through `rdfs:subClassOf` triples, which a dataset without
+ * inference does not have. With one class the qualified shape is `[ sh:class C ]`. Sub-shapes
+ * registered only in another process are missing until a process that knows them syncs.
+ *
  * One constraint per accessor, written only by the class that declares it: subclasses inherit
- * the property but add no constraint, since the rule targets the predicate's objects whoever the
- * subject is. The declaring shape owns its constraints through `core:generatedShape`
- * (`NodeShape.generatedShapes`, `contains`): shape sync writes them nested in the shape's
- * create and deletes them with the shape.
+ * the property and are counted as owners, but add no constraint. A declaring shape without a
+ * `targetClass` gets none (its owners cannot be named). The declaring shape owns its
+ * constraints through `core:generatedShape` (`NodeShape.generatedShapes`, `contains`): shape sync
+ * writes them nested in the shape's create and deletes them with the shape; their qualified
+ * shape and `sh:or` list are blank nodes, deleted with the property shape that holds them.
  *
- * Non-owning references through other predicates are not counted, and neither is ownership
- * through two different `contains` predicates (a documented limitation). The shapes are built
- * only at sync time and are never registered in the in-memory shape registry.
+ * Ownership through two different `contains` predicates is not counted (a documented
+ * limitation). The shapes are built only at sync time and are never registered in the
+ * in-memory shape registry.
  */
 /** Suffix that turns a property shape's IRI into its generated single-owner shape's IRI. */
 const SINGLE_OWNER_SUFFIX = '.singleOwner';
@@ -43,26 +56,56 @@ export function singleOwnerShapeIri(propertyShapeIri) {
     return `${propertyShapeIri}${SINGLE_OWNER_SUFFIX}`;
 }
 /**
- * The shape's OWN `contains` properties that get a single-owner constraint: those that declare
- * a value shape and have a simple path, in declaration order.
+ * The shape's OWN `contains` properties that get a single-owner constraint: those with a simple
+ * path (every decorated `contains` property has a value shape), in declaration order.
  *
  * Inherited properties are not included; their declaring shape writes their constraint.
- * Complex paths are skipped, as the containment cascade skips them. A `contains` property
- * without a value shape is a polymorphic slot (like `sh:path`) whose value may be a shared IRI,
- * so the replace, the subject delete and the class check do not treat it as owning that value,
- * and neither does the single-owner rule.
+ * Complex paths are skipped, as the owned walk skips them.
  */
 export function singleOwnerProperties(nodeShape) {
     return getPropertyShapes(nodeShape, false).filter((ps) => ps.contains && !!ps.valueShape && !!getSimplePathId(ps.path));
 }
+/** The classes whose instances own through the shape's properties: its own and every sub-shape's. */
+function ownerClasses(nodeShape) {
+    var _a;
+    const classes = new Set();
+    for (const shape of [nodeShape, ...getSubShapes(nodeShape)]) {
+        if ((_a = shape.targetClass) === null || _a === void 0 ? void 0 : _a.id)
+            classes.add(shape.targetClass.id);
+    }
+    return [...classes].sort();
+}
+/** `[ sh:class C ]`, or `[ sh:or ( [ sh:class A ] … ) ]` for several classes. Blank once written. */
+function ownerShapeData(classes) {
+    const classShape = (id) => ({ shape: NodeShape, class: { id } });
+    if (classes.length === 1)
+        return classShape(classes[0]);
+    const list = classes.reduceRight((rest, id) => ({ shape: PathList, first: classShape(id), rest }), { id: rdf.nil.id });
+    return { shape: NodeShape, orShapes: list };
+}
+const warnedWithoutTargetClass = new Set();
 /**
  * Create-pipeline data for the generated single-owner NodeShapes of `nodeShape`, one per
  * {@link singleOwnerProperties} entry. Each is stored at
  * {@link singleOwnerShapeIri}`(${shapeIri}/${label})`: the property shape's IRI exactly as shape
- * sync writes it (`buildPropertyShapeData`).
+ * sync writes it (`buildPropertyShapeData`). Empty, with one warning per shape, when the shape
+ * has `contains` properties but no `targetClass`.
  */
 export function buildSingleOwnerConstraints(nodeShape, shapeIri) {
-    return singleOwnerProperties(nodeShape).flatMap((ps) => {
+    var _a;
+    const properties = singleOwnerProperties(nodeShape);
+    if (properties.length === 0)
+        return [];
+    if (!((_a = nodeShape.targetClass) === null || _a === void 0 ? void 0 : _a.id)) {
+        if (!warnedWithoutTargetClass.has(nodeShape.id)) {
+            warnedWithoutTargetClass.add(nodeShape.id);
+            console.warn(`[linked] Shape '${nodeShape.id}' has contains properties but no targetClass, so shape ` +
+                'sync writes no single-owner constraint for them: its owners cannot be named.');
+        }
+        return [];
+    }
+    const owners = ownerShapeData(ownerClasses(nodeShape));
+    return properties.flatMap((ps) => {
         // Always set: `singleOwnerProperties` keeps simple paths only. The guard narrows the type.
         const predicate = getSimplePathId(ps.path);
         if (!predicate)
@@ -78,8 +121,9 @@ export function buildSingleOwnerConstraints(nodeShape, shapeIri) {
                         {
                             __id: psIri,
                             label: 'owners',
-                            maxCount: 1,
                             path: serializePathToNodeData({ inv: { id: predicate } }),
+                            qualifiedValueShape: owners,
+                            qualifiedMaxCount: 1,
                         },
                     ],
                 },

package/lib/esm/shapes/singleOwnerConstraint.js.map

@@ -1 +1 @@
-{"version":3,"file":"singleOwnerConstraint.js","sourceRoot":"","sources":["../../../src/shapes/singleOwnerConstraint.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,iBAAiB,EAA6C,MAAM,oBAAoB,CAAC;AACjG,OAAO,EAAC,eAAe,EAAC,MAAM,mCAAmC,CAAC;AAClE,OAAO,EAAC,uBAAuB,EAAC,MAAM,8BAA8B,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,4FAA4F;AAC5F,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,gBAAwB;IAC1D,OAAO,GAAG,gBAAgB,GAAG,mBAAmB,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAwB;IAC5D,OAAO,iBAAiB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,MAAM,CAC/C,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,CAAC,UAAU,IAAI,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,IAAI,CAAC,CACrE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CACzC,SAAwB,EACxB,QAAgB;IAEhB,OAAO,qBAAqB,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE;QACrD,2FAA2F;QAC3F,MAAM,SAAS,GAAG,eAAe,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,mBAAmB,CAAC,GAAG,QAAQ,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3D,MAAM,KAAK,GAAG,GAAG,GAAG,SAAS,CAAC;QAC9B,OAAO,CAAC;gBACN,GAAG;gBACH,IAAI,EAAE;oBACJ,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE,CAAC,EAAC,EAAE,EAAE,SAAS,EAAC,CAAC;oBAClC,UAAU,EAAE;wBACV;4BACE,IAAI,EAAE,KAAK;4BACX,KAAK,EAAE,QAAQ;4BACf,QAAQ,EAAE,CAAC;4BACX,IAAI,EAAE,uBAAuB,CAAC,EAAC,GAAG,EAAE,EAAC,EAAE,EAAE,SAAS,EAAC,EAAC,CAAC;yBACtD;qBACF;iBACF;aACF,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,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 */\nimport {getPropertyShapes, type NodeShapeData, type PropertyShapeData} from './nodeShapeData.js';\nimport {getSimplePathId} from '../paths/normalizePropertyPath.js';\nimport {serializePathToNodeData} from './serializePathToNodeData.js';\n\n/**\n * The single-owner SHACL constraints generated from `contains` properties.\n *\n * A `contains` property says the subject owns the value node. For every such property, shape\n * sync writes one generated NodeShape stating the matching store-side rule: every object of the\n * property's predicate has at most one subject pointing at it through that predicate.\n *\n * ```turtle\n * <…/Thing/image.singleOwner> a sh:NodeShape ;\n *     core:generated true ;\n *     sh:targetObjectsOf schema:image ;\n *     sh:property <…/Thing/image.singleOwner/owners> .\n * <…/Thing/image.singleOwner/owners> a sh:PropertyShape ;\n *     sh:maxCount 1 ;\n *     sh:path [ sh:inversePath schema:image ] .\n * ```\n *\n * One constraint per accessor, written only by the class that declares it: subclasses inherit\n * the property but add no constraint, since the rule targets the predicate's objects whoever the\n * subject is. The declaring shape owns its constraints through `core:generatedShape`\n * (`NodeShape.generatedShapes`, `contains`): shape sync writes them nested in the shape's\n * create and deletes them with the shape.\n *\n * Non-owning references through other predicates are not counted, and neither is ownership\n * through two different `contains` predicates (a documented limitation). The shapes are built\n * only at sync time and are never registered in the in-memory shape registry.\n */\n\n/** Suffix that turns a property shape's IRI into its generated single-owner shape's IRI. */\nconst SINGLE_OWNER_SUFFIX = '.singleOwner';\n\n/**\n * The deterministic IRI of the generated single-owner NodeShape of one property shape:\n * `${propertyShapeIri}.singleOwner`, e.g. `…/shape/my-pkg/Thing/image.singleOwner`.\n */\nexport function singleOwnerShapeIri(propertyShapeIri: string): string {\n  return `${propertyShapeIri}${SINGLE_OWNER_SUFFIX}`;\n}\n\n/**\n * The shape's OWN `contains` properties that get a single-owner constraint: those that declare\n * a value shape and have a simple path, in declaration order.\n *\n * Inherited properties are not included; their declaring shape writes their constraint.\n * Complex paths are skipped, as the containment cascade skips them. A `contains` property\n * without a value shape is a polymorphic slot (like `sh:path`) whose value may be a shared IRI,\n * so the replace, the subject delete and the class check do not treat it as owning that value,\n * and neither does the single-owner rule.\n */\nexport function singleOwnerProperties(nodeShape: NodeShapeData): PropertyShapeData[] {\n  return getPropertyShapes(nodeShape, false).filter(\n    (ps) => ps.contains && !!ps.valueShape && !!getSimplePathId(ps.path),\n  );\n}\n\n/**\n * Create-pipeline data for the generated single-owner NodeShapes of `nodeShape`, one per\n * {@link singleOwnerProperties} entry. Each is stored at\n * {@link singleOwnerShapeIri}`(${shapeIri}/${label})`: the property shape's IRI exactly as shape\n * sync writes it (`buildPropertyShapeData`).\n */\nexport function buildSingleOwnerConstraints(\n  nodeShape: NodeShapeData,\n  shapeIri: string,\n): Array<{iri: string; data: Record<string, unknown>}> {\n  return singleOwnerProperties(nodeShape).flatMap((ps) => {\n    // Always set: `singleOwnerProperties` keeps simple paths only. The guard narrows the type.\n    const predicate = getSimplePathId(ps.path);\n    if (!predicate) return [];\n    const iri = singleOwnerShapeIri(`${shapeIri}/${ps.label}`);\n    const psIri = `${iri}/owners`;\n    return [{\n      iri,\n      data: {\n        generated: true,\n        targetObjectsOf: [{id: predicate}],\n        properties: [\n          {\n            __id: psIri,\n            label: 'owners',\n            maxCount: 1,\n            path: serializePathToNodeData({inv: {id: predicate}}),\n          },\n        ],\n      },\n    }];\n  });\n}\n"]}
+{"version":3,"file":"singleOwnerConstraint.js","sourceRoot":"","sources":["../../../src/shapes/singleOwnerConstraint.ts"],"names":[],"mappings":"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","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 */\nimport {getPropertyShapes, type NodeShapeData, type PropertyShapeData} from './nodeShapeData.js';\nimport {getSimplePathId} from '../paths/normalizePropertyPath.js';\nimport {serializePathToNodeData} from './serializePathToNodeData.js';\nimport {getSubShapes} from '../utils/ShapeClass.js';\nimport {NodeShape} from './SHACL.js';\nimport {PathList} from './PathList.js';\nimport {rdf} from '../ontologies/rdf.js';\n\n/**\n * The single-owner SHACL constraints generated from `contains` properties.\n *\n * A `contains` property says the subject owns the value node, and only that property does: a\n * plain property on the same predicate is a reference. For every such property, shape sync\n * writes one generated NodeShape stating the matching store-side rule: every object of the\n * property's predicate has at most one subject pointing at it through that predicate *that is\n * an instance of the declaring class or of a registered sub-shape's class*.\n *\n * ```turtle\n * <…/Thing/image.singleOwner> a sh:NodeShape ;\n *     core:generated true ;\n *     sh:targetObjectsOf schema:image ;\n *     sh:property <…/Thing/image.singleOwner/owners> .\n * <…/Thing/image.singleOwner/owners> a sh:PropertyShape ;\n *     sh:path [ sh:inversePath schema:image ] ;\n *     sh:qualifiedValueShape [ sh:or ( [ sh:class schema:Thing ] [ sh:class ex:Project ] ) ] ;\n *     sh:qualifiedMaxCount 1 .\n * ```\n *\n * The owner classes are enumerated rather than left to `sh:class` alone, because `sh:class`\n * matches a subclass instance only through `rdfs:subClassOf` triples, which a dataset without\n * inference does not have. With one class the qualified shape is `[ sh:class C ]`. Sub-shapes\n * registered only in another process are missing until a process that knows them syncs.\n *\n * One constraint per accessor, written only by the class that declares it: subclasses inherit\n * the property and are counted as owners, but add no constraint. A declaring shape without a\n * `targetClass` gets none (its owners cannot be named). The declaring shape owns its\n * constraints through `core:generatedShape` (`NodeShape.generatedShapes`, `contains`): shape sync\n * writes them nested in the shape's create and deletes them with the shape; their qualified\n * shape and `sh:or` list are blank nodes, deleted with the property shape that holds them.\n *\n * Ownership through two different `contains` predicates is not counted (a documented\n * limitation). The shapes are built only at sync time and are never registered in the\n * in-memory shape registry.\n */\n\n/** Suffix that turns a property shape's IRI into its generated single-owner shape's IRI. */\nconst SINGLE_OWNER_SUFFIX = '.singleOwner';\n\n/**\n * The deterministic IRI of the generated single-owner NodeShape of one property shape:\n * `${propertyShapeIri}.singleOwner`, e.g. `…/shape/my-pkg/Thing/image.singleOwner`.\n */\nexport function singleOwnerShapeIri(propertyShapeIri: string): string {\n  return `${propertyShapeIri}${SINGLE_OWNER_SUFFIX}`;\n}\n\n/**\n * The shape's OWN `contains` properties that get a single-owner constraint: those with a simple\n * path (every decorated `contains` property has a value shape), in declaration order.\n *\n * Inherited properties are not included; their declaring shape writes their constraint.\n * Complex paths are skipped, as the owned walk skips them.\n */\nexport function singleOwnerProperties(nodeShape: NodeShapeData): PropertyShapeData[] {\n  return getPropertyShapes(nodeShape, false).filter(\n    (ps) => ps.contains && !!ps.valueShape && !!getSimplePathId(ps.path),\n  );\n}\n\n/** The classes whose instances own through the shape's properties: its own and every sub-shape's. */\nfunction ownerClasses(nodeShape: NodeShapeData): string[] {\n  const classes = new Set<string>();\n  for (const shape of [nodeShape, ...getSubShapes(nodeShape)]) {\n    if (shape.targetClass?.id) classes.add(shape.targetClass.id);\n  }\n  return [...classes].sort();\n}\n\n/** `[ sh:class C ]`, or `[ sh:or ( [ sh:class A ] … ) ]` for several classes. Blank once written. */\nfunction ownerShapeData(classes: string[]): Record<string, unknown> {\n  const classShape = (id: string) => ({shape: NodeShape, class: {id}});\n  if (classes.length === 1) return classShape(classes[0]);\n  const list = classes.reduceRight<unknown>(\n    (rest, id) => ({shape: PathList, first: classShape(id), rest}),\n    {id: rdf.nil.id},\n  );\n  return {shape: NodeShape, orShapes: list};\n}\n\nconst warnedWithoutTargetClass = new Set<string>();\n\n/**\n * Create-pipeline data for the generated single-owner NodeShapes of `nodeShape`, one per\n * {@link singleOwnerProperties} entry. Each is stored at\n * {@link singleOwnerShapeIri}`(${shapeIri}/${label})`: the property shape's IRI exactly as shape\n * sync writes it (`buildPropertyShapeData`). Empty, with one warning per shape, when the shape\n * has `contains` properties but no `targetClass`.\n */\nexport function buildSingleOwnerConstraints(\n  nodeShape: NodeShapeData,\n  shapeIri: string,\n): Array<{iri: string; data: Record<string, unknown>}> {\n  const properties = singleOwnerProperties(nodeShape);\n  if (properties.length === 0) return [];\n  if (!nodeShape.targetClass?.id) {\n    if (!warnedWithoutTargetClass.has(nodeShape.id)) {\n      warnedWithoutTargetClass.add(nodeShape.id);\n      console.warn(\n        `[linked] Shape '${nodeShape.id}' has contains properties but no targetClass, so shape ` +\n          'sync writes no single-owner constraint for them: its owners cannot be named.',\n      );\n    }\n    return [];\n  }\n  const owners = ownerShapeData(ownerClasses(nodeShape));\n  return properties.flatMap((ps) => {\n    // Always set: `singleOwnerProperties` keeps simple paths only. The guard narrows the type.\n    const predicate = getSimplePathId(ps.path);\n    if (!predicate) return [];\n    const iri = singleOwnerShapeIri(`${shapeIri}/${ps.label}`);\n    const psIri = `${iri}/owners`;\n    return [{\n      iri,\n      data: {\n        generated: true,\n        targetObjectsOf: [{id: predicate}],\n        properties: [\n          {\n            __id: psIri,\n            label: 'owners',\n            path: serializePathToNodeData({inv: {id: predicate}}),\n            qualifiedValueShape: owners,\n            qualifiedMaxCount: 1,\n          },\n        ],\n      },\n    }];\n  });\n}\n"]}

package/lib/esm/shapes/syncShapes.d.ts

@@ -7,6 +7,33 @@ import type { IDataset } from '../interfaces/IDataset.js';
  * @internal Exported for tests only — not part of the public API.
  */
 export declare function buildPropertyShapeData(ps: PropertyShapeData, shapeIri: string): Record<string, unknown>;
+/**
+ * Version of the {@link shapeSyncHash} input. Bump it whenever core changes the SHACL it writes
+ * for a shape (a serialization change that the create data itself does not show), so every stored
+ * shape is rewritten once by the next sync. Without a bump, stores keep the old triples: their
+ * stored hashes still match, so the sync skips them.
+ *
+ * Enforced by `shape-sync-output-equivalence.test.ts`: its golden SHACL output is recorded in
+ * `SHAPE_HASH_LEDGER` with the version it was generated for, and regenerating the golden without
+ * bumping this constant fails that test. To change the output: bump this by one, update the
+ * golden, and append `{version, goldenDigest}` to the ledger (never edit an existing entry).
+ *
+ * @internal Exported for tests only — not part of the public API.
+ */
+export declare const SHAPE_HASH_VERSION = 1;
+/**
+ * The content hash shape sync stores on a NodeShape as `core:shapeHash`: SHA-256 (hex) of the
+ * canonical form of the shape IRI and the exact create data the sync writes for it — the
+ * NodeShape, its flattened own + inherited property shapes, their `sh:in` lists and paths, and
+ * the generated single-owner shapes it owns (whose owner classes come from the registered
+ * sub-shapes, so registering a new sub-shape changes the hash of the declaring shape).
+ *
+ * Deterministic across processes, runtimes and Node versions: no blank-node labels, no object key
+ * order, no array order (see {@link canonicalize}).
+ *
+ * @internal Exported for tests only — not part of the public API.
+ */
+export declare function shapeSyncHash(data: Record<string, unknown>, shapeIri: string): string;
 /** Options controlling how {@link syncShapes} treats store shapes that are not in code. */
 export interface SyncShapesOptions {
     /**
@@ -27,6 +54,18 @@ export interface SyncShapesOptions {
      * `'all'` and `'ownedNamespaces'` are destructive and must be requested explicitly.
      */
     orphanScope?: 'all' | 'ownedNamespaces' | 'none';
+    /**
+     * Rewrite every code shape, even one whose stored `core:shapeHash` matches. Default `false`:
+     * a shape is rewritten only when its hash differs or is missing. Use it to repair a shape
+     * whose stored subtree was edited or partly deleted outside shape sync (the hash describes
+     * what sync last wrote, not what is in the store now).
+     */
+    force?: boolean;
+}
+/** Options for {@link syncShape}. */
+export interface SyncShapeOptions {
+    /** Rewrite the shape even when its stored `core:shapeHash` matches. See {@link SyncShapesOptions.force}. */
+    force?: boolean;
 }
 /**
  * Plan an idempotent sync of all code-registered (non-framework) NodeShapes into the store as
@@ -39,6 +78,15 @@ export interface SyncShapesOptions {
  * Each in-code shape's thunk runs `delete → create` in order (the delete cascade-cleans the old
  * property shapes / list / path subtrees via the containment cascade, the create rebuilds them).
  *
+ * **Unchanged shapes are skipped.** The create stores a content hash of everything it writes for
+ * the shape on the NodeShape (`core:shapeHash`, see {@link shapeSyncHash}). The plan reads the
+ * stored hashes of all code shapes in one select and builds a thunk only for a shape whose hash
+ * is missing (never synced, or synced before hashes existed) or differs. Syncing an unchanged
+ * app therefore returns no write thunks, and the length of the plan is the number of shapes
+ * actually written plus the pruned orphans. The hash records what sync last wrote, not what the
+ * store holds now: a subtree edited or partly deleted by another writer while the NodeShape and
+ * its hash survive is not detected. `options.force` rewrites every code shape.
+ *
  * **Shapes in the store but not registered in this process are left alone by default**
  * (`orphanScope: 'none'`). The registry only holds what this process happened to import, and
  * that is routinely a subset of what the dataset holds: shapes are deep-importable one file at a
@@ -55,8 +103,8 @@ export interface SyncShapesOptions {
  * with `'none'` no read is made.
  *
  * `ds` (optional) targets an explicit dataset instead of the global router. It is a **plan-time**
- * parameter: it feeds both the orphan-detection read (so orphans are computed against the same
- * store they'll be pruned from) and every delete/create thunk. Omitted → the global router;
+ * parameter: it feeds the stored-hash read and the orphan-detection read (so both are computed
+ * against the same store they'll be written to) and every delete/create thunk. Omitted → the global router;
  * the returned thunks stay nullary either way.
  */
 export declare function syncShapes(ds?: IDataset, options?: SyncShapesOptions): Promise<Array<() => Promise<void>>>;
@@ -71,9 +119,12 @@ export declare function syncShapes(ds?: IDataset, options?: SyncShapesOptions):
  *   its registered class via `getShapeClass`; the shape must be code-registered.
  * @param ds optional explicit dataset to materialize into (a store or a router) — both the delete
  *   and the create run against it instead of the global router. Omitted → global behavior.
+ * @param options `force: true` rewrites the shape even when its stored hash matches.
  * @returns a single unexecuted thunk (consistent with {@link syncShapes}), so callers can batch
  *   several together — e.g. a shape plus its referenced object-property shapes:
  *   `await Promise.all([syncShape(Person), syncShape(Address)].map((run) => run()))`.
+ *   Unless `force` is set, the thunk first reads the shape's stored `core:shapeHash` and writes
+ *   nothing when it equals the hash of what it would write (see {@link syncShapes}).
  * @throws if `target` is a framework/meta shape, is not registered, or has no `.shape`.
  */
-export declare function syncShape(target: typeof Shape | string, ds?: IDataset): () => Promise<void>;
+export declare function syncShape(target: typeof Shape | string, ds?: IDataset, options?: SyncShapeOptions): () => Promise<void>;

package/lib/esm/shapes/syncShapes.js

@@ -19,6 +19,8 @@ import { DeleteBuilder } from '../queries/DeleteBuilder.js';
 import { rdfList } from './List.js';
 import { serializePathToNodeData } from './serializePathToNodeData.js';
 import { buildSingleOwnerConstraints } from './singleOwnerConstraint.js';
+import { QueryBuilder } from '../queries/QueryBuilder.js';
+import { sha256Hex } from '../utils/sha256.js';
 /**
  * The npm scope of framework shapes (NodeShape/PropertyShape/List/PathNode/Shape) that
  * describe the meta-model itself and must never be synced as user data.
@@ -129,16 +131,112 @@ function buildNodeShapeData(nodeShape, shapeIri) {
     }
     return d;
 }
+/**
+ * Version of the {@link shapeSyncHash} input. Bump it whenever core changes the SHACL it writes
+ * for a shape (a serialization change that the create data itself does not show), so every stored
+ * shape is rewritten once by the next sync. Without a bump, stores keep the old triples: their
+ * stored hashes still match, so the sync skips them.
+ *
+ * Enforced by `shape-sync-output-equivalence.test.ts`: its golden SHACL output is recorded in
+ * `SHAPE_HASH_LEDGER` with the version it was generated for, and regenerating the golden without
+ * bumping this constant fails that test. To change the output: bump this by one, update the
+ * golden, and append `{version, goldenDigest}` to the ledger (never edit an existing entry).
+ *
+ * @internal Exported for tests only — not part of the public API.
+ */
+export const SHAPE_HASH_VERSION = 1;
+/**
+ * A canonical string for create-pipeline data: equal for equal data, independent of object key
+ * order and of the order of array values.
+ *
+ * Arrays are sorted because in create data an array is always a multi-valued property (a set of
+ * RDF values: `properties`, `generatedShapes`, `targetObjectsOf`, …). Ordered `rdf:List`s
+ * (`sh:in`, sequence and alternative paths, `sh:or`) are nested `first`/`rest` objects, so their
+ * order is kept by the structure. A shape class value (`shape: List`) is written as its NodeShape
+ * IRI. Values without ids (blank nodes once written) are compared by structure, so no blank-node
+ * label is ever part of the input.
+ */
+function canonicalize(value) {
+    var _a, _b;
+    if (value === null || value === undefined)
+        return 'null';
+    switch (typeof value) {
+        case 'string':
+            return JSON.stringify(value);
+        case 'number':
+            return `n:${Object.is(value, -0) ? '0' : String(value)}`;
+        case 'boolean':
+            return `b:${value}`;
+        case 'bigint':
+            return `i:${value.toString()}`;
+        case 'function': {
+            const shapeId = (_a = value.shape) === null || _a === void 0 ? void 0 : _a.id;
+            return `c:${JSON.stringify((_b = shapeId !== null && shapeId !== void 0 ? shapeId : value.name) !== null && _b !== void 0 ? _b : '')}`;
+        }
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalize).sort().join(',')}]`;
+    }
+    if (value instanceof Date)
+        return `d:${value.toISOString()}`;
+    if (value instanceof RegExp)
+        return `r:${JSON.stringify(value.source)}/${value.flags}`;
+    const record = value;
+    const keys = Object.keys(record)
+        .filter((k) => record[k] !== undefined)
+        .sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(record[k])}`).join(',')}}`;
+}
+/**
+ * The content hash shape sync stores on a NodeShape as `core:shapeHash`: SHA-256 (hex) of the
+ * canonical form of the shape IRI and the exact create data the sync writes for it — the
+ * NodeShape, its flattened own + inherited property shapes, their `sh:in` lists and paths, and
+ * the generated single-owner shapes it owns (whose owner classes come from the registered
+ * sub-shapes, so registering a new sub-shape changes the hash of the declaring shape).
+ *
+ * Deterministic across processes, runtimes and Node versions: no blank-node labels, no object key
+ * order, no array order (see {@link canonicalize}).
+ *
+ * @internal Exported for tests only — not part of the public API.
+ */
+export function shapeSyncHash(data, shapeIri) {
+    return sha256Hex(`linked-shape-sync/${SHAPE_HASH_VERSION}\n${canonicalize({ iri: shapeIri, data })}`);
+}
+/** The create data and its content hash for one shape, as the sync writes it. */
+function buildSyncData(nodeShape, iri) {
+    const data = buildNodeShapeData(nodeShape, iri);
+    return { data, hash: shapeSyncHash(data, iri) };
+}
+/**
+ * The stored `core:shapeHash` of each of `iris` that exists as a NodeShape, in one select. A shape
+ * that is absent, or stored without a hash (written before hashes existed), is missing from the
+ * map. `ds` targets an explicit dataset, as for the writes.
+ */
+function readStoredHashes(iris, ds) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const stored = new Map();
+        if (iris.length === 0)
+            return stored;
+        const rows = (_a = (yield QueryBuilder.from(NodeShape).select(['shapeHash']).forAll(iris).exec(ds))) !== null && _a !== void 0 ? _a : [];
+        for (const row of rows) {
+            if (row && typeof row.shapeHash === 'string')
+                stored.set(row.id, row.shapeHash);
+        }
+        return stored;
+    });
+}
 /**
  * The per-shape `delete → create` thunk shared by `syncShapes()` and `syncShape()`: exactly two
  * requests. The delete cascade-cleans the shape's old property-shape / list / path subtrees; the
- * create rebuilds them.
+ * create rebuilds them, and stores the content hash (`core:shapeHash`) of what it wrote on the
+ * NodeShape so a later sync can skip the shape while it is unchanged.
  *
  * The single-owner constraints generated from the shape's own `contains` properties
  * (`${iri}/${label}.singleOwner`, see `singleOwnerConstraint.ts`) are owned by the shape through
  * `core:generatedShape` (a `contains` property with value shape NodeShape). The delete removes
- * each one's own triples (the immediate owned-child block) and their property shapes and path
- * nodes (the dependent cascade); the create writes the current ones nested, in the same request
+ * them and their property shapes through the owned walk, and their blank path and qualified-shape
+ * nodes through the blank-node cascade; the create writes the current ones nested, in the same request
  * as the shape. A removed or renamed accessor therefore loses its constraint on the next sync,
  * and a NodeShape the shape does not own is never touched.
  *
@@ -146,12 +244,16 @@ function buildNodeShapeData(nodeShape, shapeIri) {
  * global router. Omitted → today's global behavior.
  */
 function buildSyncThunk(nodeShape, iri, ds) {
-    return () => __awaiter(this, void 0, void 0, function* () {
-        // Build the data fresh on each invocation, so every run writes from the current
-        // shape metadata.
-        const data = buildNodeShapeData(nodeShape, iri);
+    // `writeShape` builds the data fresh on each invocation, so every run writes from the current
+    // shape metadata, and the hash stored with it always describes what was written.
+    return () => writeShape(nodeShape, iri, ds);
+}
+/** Delete (cascade) then create one shape, storing the hash of the written data. */
+function writeShape(nodeShape, iri, ds) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { data, hash } = buildSyncData(nodeShape, iri);
         yield DeleteBuilder.from(NodeShape, { id: iri }).exec(ds);
-        yield NodeShape.create(data).withId(iri).exec(ds);
+        yield NodeShape.create(Object.assign(Object.assign({}, data), { shapeHash: hash })).withId(iri).exec(ds);
     });
 }
 /** The generated single-owner shape IRIs a code shape writes. */
@@ -182,6 +284,15 @@ function shapeNamespace(iri) {
  * Each in-code shape's thunk runs `delete → create` in order (the delete cascade-cleans the old
  * property shapes / list / path subtrees via the containment cascade, the create rebuilds them).
  *
+ * **Unchanged shapes are skipped.** The create stores a content hash of everything it writes for
+ * the shape on the NodeShape (`core:shapeHash`, see {@link shapeSyncHash}). The plan reads the
+ * stored hashes of all code shapes in one select and builds a thunk only for a shape whose hash
+ * is missing (never synced, or synced before hashes existed) or differs. Syncing an unchanged
+ * app therefore returns no write thunks, and the length of the plan is the number of shapes
+ * actually written plus the pruned orphans. The hash records what sync last wrote, not what the
+ * store holds now: a subtree edited or partly deleted by another writer while the NodeShape and
+ * its hash survive is not detected. `options.force` rewrites every code shape.
+ *
  * **Shapes in the store but not registered in this process are left alone by default**
  * (`orphanScope: 'none'`). The registry only holds what this process happened to import, and
  * that is routinely a subset of what the dataset holds: shapes are deep-importable one file at a
@@ -198,8 +309,8 @@ function shapeNamespace(iri) {
  * with `'none'` no read is made.
  *
  * `ds` (optional) targets an explicit dataset instead of the global router. It is a **plan-time**
- * parameter: it feeds both the orphan-detection read (so orphans are computed against the same
- * store they'll be pruned from) and every delete/create thunk. Omitted → the global router;
+ * parameter: it feeds the stored-hash read and the orphan-detection read (so both are computed
+ * against the same store they'll be written to) and every delete/create thunk. Omitted → the global router;
  * the returned thunks stay nullary either way.
  */
 export function syncShapes(ds, options) {
@@ -233,8 +344,15 @@ export function syncShapes(ds, options) {
         // Namespaces this process actually writes — the ownership scope for `'ownedNamespaces'` pruning.
         const ownedNamespaces = new Set(userShapes.map((s) => shapeNamespace(s.iri)));
         const thunks = [];
-        // 2. Per in-code shape: delete (cascade) then recreate.
+        // 2. Per in-code shape whose stored content hash is missing or differs: delete (cascade) then
+        //    recreate. An unchanged shape gets no thunk, so syncing an unchanged app writes nothing.
+        //    The stored hashes are read in one select, against the same `ds` the thunks target.
+        const storedHashes = (options === null || options === void 0 ? void 0 : options.force)
+            ? new Map()
+            : yield readStoredHashes(userShapes.map((s) => s.iri), ds);
         for (const { iri, nodeShape } of userShapes) {
+            if (!(options === null || options === void 0 ? void 0 : options.force) && storedHashes.get(iri) === buildSyncData(nodeShape, iri).hash)
+                continue;
             thunks.push(buildSyncThunk(nodeShape, iri, ds));
         }
         // 3. Orphan sweep (unless disabled). Identity-read existing NodeShape IRIs (ids only). Must hit
@@ -267,12 +385,15 @@ export function syncShapes(ds, options) {
  *   its registered class via `getShapeClass`; the shape must be code-registered.
  * @param ds optional explicit dataset to materialize into (a store or a router) — both the delete
  *   and the create run against it instead of the global router. Omitted → global behavior.
+ * @param options `force: true` rewrites the shape even when its stored hash matches.
  * @returns a single unexecuted thunk (consistent with {@link syncShapes}), so callers can batch
  *   several together — e.g. a shape plus its referenced object-property shapes:
  *   `await Promise.all([syncShape(Person), syncShape(Address)].map((run) => run()))`.
+ *   Unless `force` is set, the thunk first reads the shape's stored `core:shapeHash` and writes
+ *   nothing when it equals the hash of what it would write (see {@link syncShapes}).
  * @throws if `target` is a framework/meta shape, is not registered, or has no `.shape`.
  */
-export function syncShape(target, ds) {
+export function syncShape(target, ds, options) {
     // Normalize target → its registered shape class.
     const cls = typeof target === 'string' ? getShapeClass(target) : target;
     if (typeof target === 'string' && !cls) {
@@ -292,6 +413,13 @@ export function syncShape(target, ds) {
         throw new Error(`syncShape: refusing to sync framework/meta shape ${iri}`);
     }
     assertNoGeneratedIriCollision(nodeShape, iri, (id) => !!getShapeClass(id));
-    return buildSyncThunk(nodeShape, iri, ds);
+    if (options === null || options === void 0 ? void 0 : options.force)
+        return buildSyncThunk(nodeShape, iri, ds);
+    return () => __awaiter(this, void 0, void 0, function* () {
+        const stored = yield readStoredHashes([iri], ds);
+        if (stored.get(iri) === buildSyncData(nodeShape, iri).hash)
+            return;
+        yield writeShape(nodeShape, iri, ds);
+    });
 }
 //# sourceMappingURL=syncShapes.js.map