@nesso-how/vocab-learning 0.1.0-alpha.41 → 0.2.0-beta.0

package/README.md

@@ -37,8 +37,9 @@ const freshNode = defaultConceptReviewFields()
 import { deserialize, serialize, type NessoGraphDocument } from '@nesso-how/vocab-learning'
 
 const json = serialize({
+  vocabulary: { id: '@nesso-how/vocab-learning', version: '0.1.0' },
   name: 'My graph',
-  concepts: [{ id: 'n1', label: 'Idea', x: 0, y: 0, data: { elaboration: { ... } } }],
+  concepts: [{ id: 'n1', label: 'Idea', x: 0, y: 0, data: { elaboration: { definition: '...' } } }],
   relations: [{ id: 'e1', source: 'n1', target: 'n2', type: 'causes' }],
 })
 const doc: NessoGraphDocument = deserialize(json)
@@ -48,6 +49,16 @@ const doc: NessoGraphDocument = deserialize(json)
 
 Relation types reference: [Relation types](https://nesso.how/docs/reference/relation-types/).
 
+## Persisted vocabulary compatibility
+
+Learning-vocabulary documents must declare
+`@nesso-how/vocab-learning` and a supported normative vocabulary version.
+The first protected baseline is vocabulary `0.1.0` with definition-only
+concept elaboration.
+
+Removed alpha-only `examples`, `notes`, and image fields are not migrated or
+discarded. Documents containing them are rejected.
+
 ## License
 
 MIT

package/dist/document.d.ts

@@ -1,5 +1,25 @@
 import type { NessoGraphDocument, NessoGraphDocumentInput } from './graphDocument.js';
-/** Serialize a Nesso Learning Vocabulary graph document to JSON. */
+/**
+ * Strict post-migration document shape validation.
+ * Rejects: missing/foreign vocabulary, newer vocabulary versions, non-current
+ * vocabulary versions (older versions should be migrated before calling this),
+ * extra elaboration keys, and unknown relation types.
+ */
+export declare function validateNessoDocument<M extends Record<string, unknown>>(doc: NessoGraphDocument<M>): NessoGraphDocument<M>;
+/**
+ * Parse a Nesso graph document envelope without vocabulary-level validation.
+ * Validates JSON structure and schema format only; vocabulary identity, version,
+ * elaboration shape, and relation types are NOT checked. Callers must run
+ * {@link validateNessoDocument} (or equivalent checks) before the document
+ * reaches the store.
+ */
+export declare function deserializeEnvelope<M extends Record<string, unknown> = Record<string, unknown>>(json: string): NessoGraphDocument<M>;
+/** Serialize a Nesso Learning Vocabulary graph document to JSON. Always injects the current vocabulary metadata. */
 export declare function serialize<M extends Record<string, unknown>>(doc: NessoGraphDocumentInput<M>): string;
-/** Parse and validate a Nesso Learning Vocabulary graph document. */
+/**
+ * Parse and strictly validate a Nesso Learning Vocabulary graph document.
+ * This is the convenience entry point that does envelope parsing + full
+ * validation. Use {@link deserializeEnvelope} + manual checks when vocabulary
+ * migration must run between parsing and validation.
+ */
 export declare function deserialize<M extends Record<string, unknown> = Record<string, unknown>>(json: string): NessoGraphDocument<M>;

package/dist/document.js

@@ -4,40 +4,105 @@
 // and adds validation (elaboration shape, known `relation.type` ids).
 import { deserialize as deserializeSchema, serialize as serializeSchema } from '@nesso-how/schema';
 import { RELATION_TYPES } from './relationTypes.js';
+import { VOCABULARY } from './vocabularyIdentity.js';
 const VALID_RELATION_TYPES = new Set(Object.keys(RELATION_TYPES));
 function asRecord(value) {
     return typeof value === 'object' && value !== null ? value : null;
 }
-function validateElaboration(value, path) {
-    const elab = asRecord(value);
-    if (!elab) {
-        throw new Error(`Invalid Nesso graph document: ${path}.elaboration must be an object`);
+/** Compare two semver strings. Returns positive if a > b, negative if a < b, 0 if equal. */
+function compareVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const na = pa[i] ?? 0;
+        const nb = pb[i] ?? 0;
+        if (Number.isNaN(na) || Number.isNaN(nb))
+            return 0;
+        if (na > nb)
+            return 1;
+        if (na < nb)
+            return -1;
+    }
+    return 0;
+}
+/**
+ * Validate vocabulary identity: ensures a vocabulary is declared, its id matches
+ * the learning vocabulary, and its version is not newer than current (forward guard).
+ * Older versions pass through so the normalizer can migrate them.
+ */
+function validateVocabularyIdentity(vocabulary) {
+    if (vocabulary === undefined) {
+        throw new Error('Graph document must declare a vocabulary');
     }
-    if (typeof elab.definition !== 'string') {
-        throw new Error(`Invalid Nesso graph document: ${path}.elaboration.definition must be a string`);
+    if (vocabulary.id !== VOCABULARY.id) {
+        throw new Error(`Unsupported graph vocabulary: ${vocabulary.id}`);
+    }
+    // Forward guard: reject documents from a newer vocabulary version.
+    if (compareVersions(vocabulary.version, VOCABULARY.version) > 0) {
+        throw new Error(`Unsupported learning vocabulary version: ${vocabulary.version}`);
     }
 }
-function validateNessoDocument(doc) {
-    for (let i = 0; i < doc.concepts.length; i++) {
-        const data = doc.concepts[i].data;
-        if (data?.elaboration !== undefined) {
-            validateElaboration(data.elaboration, `concepts[${i}].data`);
-        }
+function validateElaboration(value) {
+    const elab = asRecord(value);
+    if (!elab ||
+        typeof elab.definition !== 'string' ||
+        Object.keys(elab).length !== 1 ||
+        !Object.hasOwn(elab, 'definition')) {
+        throw new Error('Concept elaboration must contain only definition');
     }
+}
+function validateRelations(doc) {
     for (let i = 0; i < doc.relations.length; i++) {
         const rel = doc.relations[i];
         if (rel.type !== undefined && !VALID_RELATION_TYPES.has(rel.type)) {
             throw new Error(`Invalid Nesso graph document: unknown relation type "${rel.type}" at relations[${i}]`);
         }
     }
+}
+/**
+ * Strict post-migration document shape validation.
+ * Rejects: missing/foreign vocabulary, newer vocabulary versions, non-current
+ * vocabulary versions (older versions should be migrated before calling this),
+ * extra elaboration keys, and unknown relation types.
+ */
+export function validateNessoDocument(doc) {
+    validateVocabularyIdentity(doc.vocabulary);
+    // After migration the version must match exactly.
+    if (doc.vocabulary.version !== VOCABULARY.version) {
+        throw new Error(`Unsupported learning vocabulary version: ${doc.vocabulary.version}`);
+    }
+    for (let i = 0; i < doc.concepts.length; i++) {
+        const data = doc.concepts[i].data;
+        if (data?.elaboration !== undefined) {
+            validateElaboration(data.elaboration);
+        }
+    }
+    validateRelations(doc);
     return doc;
 }
-/** Serialize a Nesso Learning Vocabulary graph document to JSON. */
+/**
+ * Parse a Nesso graph document envelope without vocabulary-level validation.
+ * Validates JSON structure and schema format only; vocabulary identity, version,
+ * elaboration shape, and relation types are NOT checked. Callers must run
+ * {@link validateNessoDocument} (or equivalent checks) before the document
+ * reaches the store.
+ */
+export function deserializeEnvelope(json) {
+    return deserializeSchema(json);
+}
+/** Serialize a Nesso Learning Vocabulary graph document to JSON. Always injects the current vocabulary metadata. */
 export function serialize(doc) {
-    return serializeSchema(doc);
+    return serializeSchema({
+        ...doc,
+        vocabulary: VOCABULARY,
+    });
 }
-/** Parse and validate a Nesso Learning Vocabulary graph document. */
+/**
+ * Parse and strictly validate a Nesso Learning Vocabulary graph document.
+ * This is the convenience entry point that does envelope parsing + full
+ * validation. Use {@link deserializeEnvelope} + manual checks when vocabulary
+ * migration must run between parsing and validation.
+ */
 export function deserialize(json) {
-    const doc = deserializeSchema(json);
-    return validateNessoDocument(doc);
+    return validateNessoDocument(deserializeEnvelope(json));
 }

package/dist/index.d.ts

@@ -1,12 +1,6 @@
 export type { ConceptElaboration, NessoConceptData, NessoRelationData, NessoGraphDocument, NessoGraphDocumentInput, } from './graphDocument.js';
-/** OKG vocabulary identity — version bumps only on normative vocabulary changes, not npm releases. */
-export declare const VOCABULARY: {
-    readonly id: "@nesso-how/vocab-learning";
-    readonly name: "Nesso Learning Vocabulary";
-    readonly domain: "learning";
-    readonly version: "0.1.0";
-};
+export { VOCABULARY } from './vocabularyIdentity.js';
 export { defaultConceptReviewFields, type ConceptNodeData, type LearningNodeParams, } from './nodeParams.js';
 export { RELATION_CATEGORIES, RELATION_TYPES, RELATION_TYPE_VALUES, isPrimaryRelationType, type Cardinality, type GlyphKind, type Polarity, type RelationCategory, type RelationTypeDef, type RelationTypeName, type Transitivity, } from './relationTypes.js';
 export { CategoryPalette, GLYPH_PATHS, PALETTES } from './visual.js';
-export { deserialize, serialize } from './document.js';
+export { deserialize, deserializeEnvelope, serialize, validateNessoDocument } from './document.js';

package/dist/index.js

@@ -2,14 +2,8 @@
 //
 // Public entry point for `@nesso-how/vocab-learning`. Re-exports the split modules
 // below; import from here unless you need a specific submodule in-package.
-/** OKG vocabulary identity — version bumps only on normative vocabulary changes, not npm releases. */
-export const VOCABULARY = {
-    id: '@nesso-how/vocab-learning',
-    name: 'Nesso Learning Vocabulary',
-    domain: 'learning',
-    version: '0.1.0',
-};
+export { VOCABULARY } from './vocabularyIdentity.js';
 export { defaultConceptReviewFields, } from './nodeParams.js';
 export { RELATION_CATEGORIES, RELATION_TYPES, RELATION_TYPE_VALUES, isPrimaryRelationType, } from './relationTypes.js';
 export { GLYPH_PATHS, PALETTES } from './visual.js';
-export { deserialize, serialize } from './document.js';
+export { deserialize, deserializeEnvelope, serialize, validateNessoDocument } from './document.js';

package/dist/vocabularyIdentity.d.ts

@@ -0,0 +1,7 @@
+/** OKG vocabulary identity — version bumps only on normative vocabulary changes, not npm releases. */
+export declare const VOCABULARY: {
+    readonly id: "@nesso-how/vocab-learning";
+    readonly name: "Nesso Learning Vocabulary";
+    readonly domain: "learning";
+    readonly version: "0.1.0";
+};

package/dist/vocabularyIdentity.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+//
+// Vocabulary identity constant shared between document validation and the public API.
+// Extracted to avoid a circular dependency: both index.ts and document.ts import it.
+/** OKG vocabulary identity — version bumps only on normative vocabulary changes, not npm releases. */
+export const VOCABULARY = {
+    id: '@nesso-how/vocab-learning',
+    name: 'Nesso Learning Vocabulary',
+    domain: 'learning',
+    version: '0.1.0',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nesso-how/vocab-learning",
-  "version": "0.1.0-alpha.41",
+  "version": "0.2.0-beta.0",
   "description": "Nesso Learning Vocabulary — graph vocabulary (relation types, node params, palettes) shared across app and MCP",
   "license": "MIT",
   "repository": {
@@ -22,7 +22,7 @@
     }
   },
   "dependencies": {
-    "@nesso-how/schema": "0.1.0-alpha.41"
+    "@nesso-how/schema": "0.2.0-beta.0"
   },
   "devDependencies": {
     "typescript": "~5.8.3"