@nesso-how/vocab-learning 0.1.0-alpha.34 → 0.1.0-alpha.35

package/README.md

@@ -1,8 +1,8 @@
 # @nesso-how/vocab-learning
 
-The **Nesso Learning Vocabulary** for [Nesso](https://nesso.how) — a self-contained graph vocabulary: 52 typed relation types in 8 categories, semantic coefficients, category palettes, and private node parameters (FSRS review fields).
+The **Nesso Learning Vocabulary** for [Nesso](https://nesso.how) — a self-contained graph vocabulary: 52 typed relation types in 8 categories, type properties, category palettes, and private node parameters (FSRS review fields).
 
-Graph JSON files declare which vocabulary they use via `VOCABULARY.id` and a normative `version`.
+Graph JSON files declare which vocabulary they use via `VOCABULARY.id` and a normative `version`. File I/O builds on [`@nesso-how/schema`](../schema/README.md) and adds learning-vocabulary validation (elaboration shape, known relation type ids).
 
 ## Install
 
@@ -12,11 +12,15 @@ npm install @nesso-how/vocab-learning
 
 ## Usage
 
+### Relation catalog and palettes
+
 ```ts
 import {
   VOCABULARY,
+  RELATION_CATEGORIES,
   RELATION_TYPES,
   RELATION_TYPE_VALUES,
+  PALETTES,
   defaultConceptReviewFields,
 } from '@nesso-how/vocab-learning'
 
@@ -27,6 +31,21 @@ const freshNode = defaultConceptReviewFields()
 // { stability: 0, difficulty: 0, due: 0, ... }
 ```
 
+### Graph document I/O
+
+```ts
+import { deserialize, serialize, type NessoGraphDocument } from '@nesso-how/vocab-learning'
+
+const json = serialize({
+  name: 'My graph',
+  concepts: [{ id: 'n1', label: 'Idea', x: 0, y: 0, data: { elaboration: { ... } } }],
+  relations: [{ id: 'e1', source: 'n1', target: 'n2', type: 'causes' }],
+})
+const doc: NessoGraphDocument = deserialize(json)
+```
+
+**Shared content vs review state.** `serialize` / `deserialize` handle the portable graph file: concept labels, positions, `elaboration`, relation types, and layout hints. FSRS fields (`stability`, `difficulty`, `due`, etc.) are runtime node parameters for spaced repetition — they are typed here via `defaultConceptReviewFields()` but are **not** written into shared graph JSON; the Nesso app persists them separately.
+
 Relation types reference: [Relation types](https://nesso.how/docs/reference/relation-types/).
 
 ## License

package/dist/document.d.ts

@@ -0,0 +1,5 @@
+import type { NessoGraphDocument, NessoGraphDocumentInput } from './graphDocument.js';
+/** Serialize a Nesso Learning Vocabulary graph document to JSON. */
+export declare function serialize<M extends Record<string, unknown>>(doc: NessoGraphDocumentInput<M>): string;
+/** Parse and validate a Nesso Learning Vocabulary graph document. */
+export declare function deserialize<M extends Record<string, unknown> = Record<string, unknown>>(json: string): NessoGraphDocument<M>;

package/dist/document.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MIT
+//
+// Learning-vocabulary graph file I/O: wraps `@nesso-how/schema` serialize/deserialize
+// 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';
+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`);
+    }
+    if (typeof elab.definition !== 'string') {
+        throw new Error(`Invalid Nesso graph document: ${path}.elaboration.definition must be a string`);
+    }
+    if (typeof elab.examples !== 'string') {
+        throw new Error(`Invalid Nesso graph document: ${path}.elaboration.examples must be a string`);
+    }
+    if (typeof elab.notes !== 'string') {
+        throw new Error(`Invalid Nesso graph document: ${path}.elaboration.notes must be a string`);
+    }
+}
+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`);
+        }
+    }
+    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}]`);
+        }
+    }
+    return doc;
+}
+/** Serialize a Nesso Learning Vocabulary graph document to JSON. */
+export function serialize(doc) {
+    return serializeSchema(doc);
+}
+/** Parse and validate a Nesso Learning Vocabulary graph document. */
+export function deserialize(json) {
+    const doc = deserializeSchema(json);
+    return validateNessoDocument(doc);
+}

package/dist/document.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/document.test.js

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+import { describe, expect, it } from 'vitest';
+import { deserialize, serialize } from './document.js';
+describe('vocab-learning serialize / deserialize', () => {
+    it('round-trips a learning vocabulary graph document', () => {
+        const doc = {
+            vocabulary: { id: '@nesso-how/vocab-learning', version: '0.1.0' },
+            name: 'Demo',
+            concepts: [
+                {
+                    id: 'n1',
+                    label: 'Idea',
+                    x: 0,
+                    y: 0,
+                    data: { elaboration: { definition: 'd', examples: 'e', notes: '' } },
+                },
+            ],
+            relations: [{ id: 'e1', source: 'n1', target: 'n1', type: 'causes' }],
+        };
+        const parsed = deserialize(serialize(doc));
+        expect(parsed.concepts[0].label).toBe('Idea');
+        expect(parsed.relations[0].type).toBe('causes');
+    });
+    it('rejects an unknown relation type', () => {
+        const json = JSON.stringify({
+            name: 'X',
+            concepts: [{ id: 'n1', label: 'n1', x: 0, y: 0 }],
+            relations: [{ id: 'e1', source: 'n1', target: 'n1', type: 'not-a-real-type' }],
+        });
+        expect(() => deserialize(json)).toThrow(/unknown relation type/);
+    });
+});

package/dist/graphDocument.d.ts

@@ -0,0 +1,20 @@
+import type { GraphDocument, GraphDocumentInput } from '@nesso-how/schema';
+export interface ConceptElaboration {
+    definition: string;
+    examples: string;
+    notes: string;
+    imageUrl?: string;
+    imageTitle?: string;
+    imageDescriptionUrl?: string;
+}
+/** Shared concept content in a Nesso graph document (no label, no FSRS). */
+export interface NessoConceptData extends Record<string, unknown> {
+    elaboration?: ConceptElaboration;
+}
+/** Shared relation content in a Nesso graph document. */
+export interface NessoRelationData extends Record<string, unknown> {
+    curveFlip?: boolean;
+    curveFlipPinned?: boolean;
+}
+export type NessoGraphDocument<M extends Record<string, unknown> = Record<string, unknown>> = GraphDocument<NessoConceptData, NessoRelationData, M>;
+export type NessoGraphDocumentInput<M extends Record<string, unknown> = Record<string, unknown>> = GraphDocumentInput<NessoConceptData, NessoRelationData, M>;

package/dist/graphDocument.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+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";
@@ -5,63 +6,7 @@ export declare const VOCABULARY: {
     readonly domain: "learning";
     readonly version: "0.1.0";
 };
-/** Private dynamic node parameters declared by the Nesso Learning Vocabulary. */
-export interface LearningNodeParams extends Record<string, unknown> {
-    stability: number;
-    difficulty: number;
-    reps: number;
-    lapses: number;
-    /** ts-fsrs State: 0=New 1=Learning 2=Review 3=Relearning */
-    fsrsState: number;
-    /** Unix ms; due when <= now (0 = new / immediate). */
-    due: number;
-    /** Unix ms; 0 = never reviewed. */
-    lastReview: number;
-    /** 0=unrated, 1=Again 2=Hard 3=Good 4=Easy (matches ts-fsrs Rating). */
-    lastRating: number;
-    /** FSRS learning-step index; optional for records saved before it existed. */
-    learningSteps?: number;
-}
-/** Fresh private params for a new or shared-import concept (no personal review history). */
-export declare function defaultConceptReviewFields(): LearningNodeParams;
-export type EdgeCategory = 'taxonomic' | 'structural' | 'causal' | 'dependency' | 'temporal' | 'opposition' | 'similarity' | 'epistemic';
-export type EdgeTypeName = 'subtype-of' | 'has-subtype' | 'instance-of' | 'has-instance' | 'part-of' | 'contains' | 'made-of' | 'composes' | 'causes' | 'caused-by' | 'produces' | 'produced-by' | 'enables' | 'enabled-by' | 'prevents' | 'prevented-by' | 'triggers' | 'triggered-by' | 'inhibits' | 'inhibited-by' | 'disables' | 'disabled-by' | 'consumes' | 'consumed-by' | 'delays' | 'delayed-by' | 'requires' | 'required-by' | 'uses' | 'used-by' | 'used-for' | 'purpose-of' | 'precedes' | 'follows' | 'occurs-in' | 'has-occurrence' | 'during' | 'spans' | 'overlaps-with' | 'derives-from' | 'gives-rise-to' | 'contrasts-with' | 'opposite-of' | 'similar-to' | 'analogous-to' | 'supports' | 'supported-by' | 'contradicts' | 'explains' | 'explained-by' | 'defines' | 'defined-by';
-export type GlyphKind = 'triangle-up' | 'circle-dot' | 'diamond' | 'diamond-open' | 'hash' | 'arrow-right' | 'asterisk' | 'key' | 'block' | 'spark' | 'anchor' | 'tool' | 'chevron-r' | 'ring' | 'tilde' | 'x' | 'minus' | 'flag' | 'approx' | 'arrows-lr' | 'check' | 'slash' | 'bulb' | 'equals' | 'lock' | 'flame' | 'hourglass' | 'brackets' | 'overlap' | 'branch';
-/** Transitivity of a relation: `Y` strict, `N` none, `weak` with decay (algorithms may discount weight per step). */
-export type Transitivity = 'Y' | 'N' | 'weak';
-/** Polarity in signed-network terms: `+1` positive effect, `-1` antagonistic, `0` neutral/structural. */
-export type Polarity = -1 | 0 | 1;
-/** Expected mapping cardinality. `N-N` means no a-priori constraint. */
-export type Cardinality = '1-1' | '1-N' | 'N-1' | 'N-N';
-export interface EdgeTypeDef {
-    cat: EdgeCategory;
-    label: string;
-    line: 'solid' | 'dashed' | 'dotted' | 'double' | 'wavy';
-    glyph: GlyphKind;
-    transitive: Transitivity;
-    /** Canonical inverse in the set; `'self'` for symmetric types. */
-    inverse: EdgeTypeName | 'self';
-    /** Per-type semantic weight in 0..1; intensity, not per-edge confidence. */
-    strength: number;
-    polarity: Polarity;
-    cardinality: Cardinality;
-}
-/** Canonical category labels and prompts. */
-export declare const RELATION_CATEGORY_META: Record<EdgeCategory, {
-    label: string;
-    subtitle: string;
-}>;
-export declare const RELATION_TYPES: Record<EdgeTypeName, EdgeTypeDef>;
-export declare const RELATION_TYPE_VALUES: EdgeTypeName[];
-/** Forward member of each inverse pair (first in `RELATION_TYPE_VALUES`); all symmetric types. */
-export declare function isPrimaryRelationType(id: EdgeTypeName): boolean;
-export type CategoryPalette = 'default' | 'vivid' | 'muted' | 'monoCat';
-/** Per-category hex colors for each named palette. */
-export declare const PALETTES: Record<CategoryPalette, Record<EdgeCategory, string>>;
-/**
- * Raw SVG inner content for each glyph kind, on a 14×14 viewBox.
- * Uses `currentColor` for stroke/fill — set CSS `color` on the parent to tint.
- * Default stroke attrs: fill=none, stroke=currentColor, stroke-width=1.4,
- * stroke-linecap=round, stroke-linejoin=round.
- */
-export declare const GLYPH_PATHS: Record<GlyphKind, string>;
+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';