glossarist 0.4.25 → 0.4.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",

package/src/diff/diff-renderer.js

@@ -222,19 +222,30 @@ function relationLabel(r) {
 // Aggregate multiplicity + delimiting stats across a concept's
 // PartitiveRelations. Used by dataset-level summaries, not by the
 // per-relation diff label.
+//
+// v4: presence and count are independent dimensions. Stats include
+// byPresence and byCount breakdowns so tools can query each axis
+// independently ("show me all optional parts" or "show me all
+// multiple-count parts").
 export function multiplicityStats(relations) {
   const byMultiplicity = {};
+  const byPresence = {};
+  const byCount = {};
   let delimitingCount = 0;
   let total = 0;
   for (const rel of relations ?? []) {
     for (const m of rel?.partitives ?? []) {
       total += 1;
-      const k = m?.multiplicity ?? 'compulsory';
-      byMultiplicity[k] = (byMultiplicity[k] ?? 0) + 1;
+      const mult = m?.multiplicity ?? 'compulsory';
+      byMultiplicity[mult] = (byMultiplicity[mult] ?? 0) + 1;
+      const p = m?.presence ?? 'required';
+      const c = m?.count ?? 'exactly_one';
+      byPresence[p] = (byPresence[p] ?? 0) + 1;
+      byCount[c] = (byCount[c] ?? 0) + 1;
       if (m?.is_delimiting === true) delimitingCount += 1;
     }
   }
-  return { total, byMultiplicity, delimiting: delimitingCount };
+  return { total, byMultiplicity, byPresence, byCount, delimiting: delimitingCount };
 }
 
 function itemLabel(item) {

package/src/migration/partitive-relation-migrator.js

@@ -54,7 +54,8 @@ export function migrateHyperedgeToRelation(v1Hash) {
   const parts = Array.isArray(v1Hash.parts) ? v1Hash.parts : [];
   out.partitives = parts.map(ref => ({
     ref: { ...ref },
-    multiplicity: 'compulsory',
+    presence: 'required',
+    count: 'exactly_one',
   }));
 
   out.completeness = _migrateEnumeration(v1Hash.enumeration);

package/src/models/index.js

@@ -38,6 +38,18 @@ export {
 // backward-compat input. New code should use v2 exclusively.
 export { PartitiveRelation } from './partitive-relation.js';
 export { PartitiveMember } from './partitive-member.js';
+export {
+  PARTITIVE_PRESENCE,
+  PARTITIVE_PRESENCE_VALUES,
+  DEFAULT_PRESENCE,
+  isValidPresence,
+} from './partitive-presence.js';
+export {
+  PARTITIVE_COUNT,
+  PARTITIVE_COUNT_VALUES,
+  DEFAULT_COUNT,
+  isValidCount,
+} from './partitive-count.js';
 export {
   COMPLETENESS,
   COMPLETENESS_VALUES,
@@ -49,6 +61,8 @@ export {
   MULTIPLICITY_VALUES,
   DEFAULT_MULTIPLICITY,
   isValidMultiplicity,
+  multiplicityFromPair,
+  pairFromMultiplicity,
 } from './multiplicity.js';
 
 // v1 → v2 migration helper. Pure function; idempotent.

package/src/models/multiplicity.js

@@ -1,24 +1,74 @@
-// Multiplicity — ISO 704:2022 partitive member multiplicity.
+// Multiplicity — ISO 704:2022 partitive multiplicity (derived view).
 //
-// Encodes the diagram line notation as structured data:
-//   compulsory          — 1 solid line (must exist in every instance)
-//   optional            — 1 dashed line (exists in some instances only)
-//   compulsory_multiple — 2 solid lines (multiple must exist)
-//   optional_multiple   — 2 dashed lines (multiple may exist)
-//   compulsory_at_least_one        — 1 solid + 1 dashed line (at least one must exist)
+// ISO 704:2022 multiplicity is the cross product of two orthogonal
+// dimensions (PartitivePresence × PartitiveCount). The 5 valid
+// combinations map to the 5 ISO 704 names:
 //
-// Defaults to `compulsory` when omitted.
+//   required × exactly_one  → compulsory
+//   optional × exactly_one  → optional
+//   required × multiple     → compulsory_multiple
+//   optional × multiple     → optional_multiple
+//   required × at_least_one → compulsory_at_least_one
+//
+// (optional × at_least_one is REDUNDANT with optional × multiple —
+// "may exist, ≥1 if it does" = "may exist in any number" — and is
+// explicitly rejected at construction with a clear error message.)
+//
+// This module is the SSOT for the (presence, count) → ISO name
+// mapping. Both MULTIPLICITY constants and MULTIPLICITY_VALUES are
+// derived from this single table; no duplicate string literals.
 
-import { makeEnum } from './enum.js';
+import { PARTITIVE_PRESENCE } from './partitive-presence.js';
+import { PARTITIVE_COUNT } from './partitive-count.js';
 
-export const MULTIPLICITY = makeEnum('MULTIPLICITY', {
-  COMPULSORY: 'compulsory',
-  OPTIONAL: 'optional',
-  COMPULSORY_MULTIPLE: 'compulsory_multiple',
-  OPTIONAL_MULTIPLE: 'optional_multiple',
-  COMPULSORY_AT_LEAST_ONE: 'compulsory_at_least_one',
+const NAME_BY_PAIR = Object.freeze({
+  [`${PARTITIVE_PRESENCE.REQUIRED}:${PARTITIVE_COUNT.EXACTLY_ONE}`]:  'compulsory',
+  [`${PARTITIVE_PRESENCE.OPTIONAL}:${PARTITIVE_COUNT.EXACTLY_ONE}`]:  'optional',
+  [`${PARTITIVE_PRESENCE.REQUIRED}:${PARTITIVE_COUNT.MULTIPLE}`]:     'compulsory_multiple',
+  [`${PARTITIVE_PRESENCE.OPTIONAL}:${PARTITIVE_COUNT.MULTIPLE}`]:     'optional_multiple',
+  [`${PARTITIVE_PRESENCE.REQUIRED}:${PARTITIVE_COUNT.AT_LEAST_ONE}`]: 'compulsory_at_least_one',
 });
 
-export const MULTIPLICITY_VALUES = MULTIPLICITY.VALUES;
+const PAIR_BY_NAME = Object.freeze(
+  Object.fromEntries(
+    Object.entries(NAME_BY_PAIR).map(([pair, name]) => [name, pair]),
+  ),
+);
+
+export const MULTIPLICITY = Object.freeze(
+  Object.fromEntries(
+    Object.values(NAME_BY_PAIR).map(name => [name.toUpperCase(), name]),
+  ),
+);
+
+export const MULTIPLICITY_VALUES = Object.freeze(Object.values(NAME_BY_PAIR));
+
 export const DEFAULT_MULTIPLICITY = MULTIPLICITY.COMPULSORY;
-export const isValidMultiplicity = MULTIPLICITY.isValid;
+
+export function multiplicityFromPair(presence, count) {
+  const name = NAME_BY_PAIR[`${presence}:${count}`];
+  if (name == null) {
+    throw invalidCombinationError(presence, count);
+  }
+  return name;
+}
+
+export function pairFromMultiplicity(name) {
+  const pair = PAIR_BY_NAME[name];
+  if (pair == null) {
+    throw new Error(`Unknown multiplicity: ${JSON.stringify(name)}`);
+  }
+  const [presence, count] = pair.split(':');
+  return { presence, count };
+}
+
+export function isValidMultiplicity(name) {
+  return Object.prototype.hasOwnProperty.call(PAIR_BY_NAME, name);
+}
+
+function invalidCombinationError(presence, count) {
+  return new Error(
+    `Invalid multiplicity combination: presence=${presence}, count=${count}. ` +
+    `(optional + at_least_one collapses to optional + multiple — use count=multiple.)`,
+  );
+}

package/src/models/partitive-count.js

@@ -0,0 +1,20 @@
+// PartitiveCount — ISO 704:2022 partitive member count.
+//
+// count (line count):
+//   exactly_one  — 1 line (exactly one instance)
+//   at_least_one — 1 solid + 1 dashed (at least one instance)
+//   multiple     — 2 lines (multiple instances)
+//
+// Default: exactly_one.
+
+import { makeEnum } from './enum.js';
+
+export const PARTITIVE_COUNT = makeEnum('PARTITIVE_COUNT', {
+  EXACTLY_ONE: 'exactly_one',
+  AT_LEAST_ONE: 'at_least_one',
+  MULTIPLE: 'multiple',
+});
+
+export const PARTITIVE_COUNT_VALUES = PARTITIVE_COUNT.VALUES;
+export const DEFAULT_COUNT = PARTITIVE_COUNT.EXACTLY_ONE;
+export const isValidCount = PARTITIVE_COUNT.isValid;

package/src/models/partitive-member.js

@@ -1,33 +1,35 @@
 // PartitiveMember — one member of a PartitiveRelation.
 //
 // Carries a ConceptRef (the subordinate concept partitive) plus
-// ISO 704:2022 multiplicity and delimiting metadata.
+// ISO 704:2022 presence + count + is_delimiting.
 //
-// ISO 704:2022 partitive member notation:
+// Matches concept-model/models/concepts/PartitiveMember.lutaml exactly:
+//   +ref            — ConceptRef [1]
+//   +presence       — PartitivePresence [0..1] (default: required)
+//   +count          — PartitiveCount [0..1] (default: exactly_one)
+//   +is_delimiting  — Boolean [0..1] (default: false)
 //
-//   multiplicity (diagram line notation):
-//     compulsory                — 1 solid line         (must exist in every instance)
-//     optional                  — 1 dashed line        (exists in some instances only)
-//     compulsory_multiple       — 2 solid lines        (multiple must exist)
-//     optional_multiple         — 2 dashed lines       (multiple may exist)
-//     compulsory_at_least_one  — 1 solid + 1 dashed   (≥1 must exist)
+// The combination (optional, at_least_one) is invalid: if a part is
+// optional, the at-least-one constraint is vacuous and collapses to
+// (optional, multiple). Rejected at construction.
 //
-//   is_delimiting (orthogonal, bold 3x-width line in diagram):
-//     A delimiting part behaves like a delimiting characteristic:
-//     it distinguishes the comprehensive from coordinate concepts.
-//
-// Whether a part is delimiting depends on the concept system, the
-// coordinate concepts, the inheritance principle, and the criterion
-// of subdivision used (ISO 704:2022 §5.5.4.2.1).
+// ISO 704 "name" strings (compulsory, optional, etc.) are NOT part of
+// the model — they're a display concern handled by multiplicityFromPair
+// in the renderer/viewer layer. The model is purely presence + count.
 
 import { GlossaristModel } from './base.js';
 import { ConceptRef } from './concept-ref.js';
 import {
-  MULTIPLICITY,
-  DEFAULT_MULTIPLICITY,
-  MULTIPLICITY_VALUES,
-  isValidMultiplicity,
-} from './multiplicity.js';
+  PARTITIVE_PRESENCE,
+  DEFAULT_PRESENCE,
+  PARTITIVE_PRESENCE_VALUES,
+  isValidPresence,
+} from './partitive-presence.js';
+import {
+  DEFAULT_COUNT,
+  PARTITIVE_COUNT_VALUES,
+  isValidCount,
+} from './partitive-count.js';
 
 export class PartitiveMember extends GlossaristModel {
   constructor(data = {}) {
@@ -35,38 +37,17 @@ export class PartitiveMember extends GlossaristModel {
     this.ref = data.ref instanceof ConceptRef
       ? data.ref
       : new ConceptRef(data.ref ?? {});
-    this.multiplicity = _resolveMultiplicity(data.multiplicity);
-    this.is_delimiting = _resolveBoolean(data.is_delimiting, 'is_delimiting');
+    this.presence = _resolvePresence(data.presence);
+    this.count = _resolveCount(data.count);
+    this.is_delimiting = data.is_delimiting === true;
 
     _assertNonEmptyRef(this.ref);
+    _assertValidCombination(this.presence, this.count);
   }
 
-  // Per-value multiplicity predicates. Each new enum value gets one
-  // line — OCP-friendly: the predicates grow with the enum without
-  // touching unrelated code. (TODO.partitive-relation-v3/05.)
-  get isCompulsory() {
-    return this.multiplicity === MULTIPLICITY.COMPULSORY;
-  }
-
-  get isOptional() {
-    return this.multiplicity === MULTIPLICITY.OPTIONAL;
-  }
-
-  get isCompulsoryMultiple() {
-    return this.multiplicity === MULTIPLICITY.COMPULSORY_MULTIPLE;
-  }
-
-  get isOptionalMultiple() {
-    return this.multiplicity === MULTIPLICITY.OPTIONAL_MULTIPLE;
-  }
-
-  get isCompulsoryAtLeastOne() {
-    return this.multiplicity === MULTIPLICITY.COMPULSORY_AT_LEAST_ONE;
-  }
-
-  get isDelimiting() {
-    return this.is_delimiting === true;
-  }
+  get isRequired() { return this.presence === PARTITIVE_PRESENCE.REQUIRED; }
+  get isOptional() { return this.presence === PARTITIVE_PRESENCE.OPTIONAL; }
+  get isDelimiting() { return this.is_delimiting === true; }
 
   identity() {
     return PartitiveMember.identityOf(this);
@@ -74,12 +55,9 @@ export class PartitiveMember extends GlossaristModel {
 
   toJSON() {
     const obj = { ref: this.ref.toJSON() };
-    if (this.multiplicity !== DEFAULT_MULTIPLICITY) {
-      obj.multiplicity = this.multiplicity;
-    }
-    if (this.is_delimiting === true) {
-      obj.is_delimiting = true;
-    }
+    if (this.presence !== DEFAULT_PRESENCE) obj.presence = this.presence;
+    if (this.count !== DEFAULT_COUNT) obj.count = this.count;
+    if (this.is_delimiting === true) obj.is_delimiting = true;
     return obj;
   }
 
@@ -94,33 +72,34 @@ export class PartitiveMember extends GlossaristModel {
   }
 }
 
-function _resolveMultiplicity(value) {
-  if (value == null) return DEFAULT_MULTIPLICITY;
-  if (!isValidMultiplicity(value)) {
-    throw new Error(
-      `invalid multiplicity ${JSON.stringify(value)}; ` +
-      `must be one of ${MULTIPLICITY_VALUES.join(', ')}`,
-    );
+function _resolvePresence(value) {
+  if (value == null) return DEFAULT_PRESENCE;
+  if (!isValidPresence(value)) {
+    throw new Error(`invalid presence ${JSON.stringify(value)}; must be one of ${PARTITIVE_PRESENCE_VALUES.join(', ')}`);
   }
   return value;
 }
 
-// Boolean coercion with strict type check. Rejects strings, numbers,
-// objects (silent coercion was the v3 bug TODO.partitive-relation-v3/02).
-function _resolveBoolean(value, fieldName) {
-  if (value == null) return false;
-  if (typeof value === 'boolean') return value;
-  throw new Error(
-    `PartitiveMember.${fieldName} must be a boolean; got ${typeof value} ` +
-    `${JSON.stringify(value)}`,
-  );
+function _resolveCount(value) {
+  if (value == null) return DEFAULT_COUNT;
+  if (!isValidCount(value)) {
+    throw new Error(`invalid count ${JSON.stringify(value)}; must be one of ${PARTITIVE_COUNT_VALUES.join(', ')}`);
+  }
+  return value;
 }
 
 function _assertNonEmptyRef(ref) {
   if (!ref.source && !ref.id && !ref.text) {
+    throw new Error('PartitiveMember#ref must be a non-empty ConceptRef (source, id, or text required)');
+  }
+}
+
+function _assertValidCombination(presence, count) {
+  if (presence === 'optional' && count === 'at_least_one') {
     throw new Error(
-      'PartitiveMember#ref must be a non-empty ConceptRef ' +
-      '(source, id, or text required)',
+      'PartitiveMember presence=optional + count=at_least_one is invalid — ' +
+      'it collapses to optional + multiple (zero or more). ' +
+      'Use presence: optional, count: multiple instead.',
     );
   }
 }

package/src/models/partitive-presence.js

@@ -0,0 +1,18 @@
+// PartitivePresence — ISO 704:2022 partitive member presence.
+//
+// presence (line style):
+//   required — solid line (must exist in every instance)
+//   optional — dashed line (may exist; exists in some instances)
+//
+// Default: required.
+
+import { makeEnum } from './enum.js';
+
+export const PARTITIVE_PRESENCE = makeEnum('PARTITIVE_PRESENCE', {
+  REQUIRED: 'required',
+  OPTIONAL: 'optional',
+});
+
+export const PARTITIVE_PRESENCE_VALUES = PARTITIVE_PRESENCE.VALUES;
+export const DEFAULT_PRESENCE = PARTITIVE_PRESENCE.REQUIRED;
+export const isValidPresence = PARTITIVE_PRESENCE.isValid;

package/src/rdf/gloss-partitive-member.js

@@ -1,32 +1,60 @@
 // PartitiveMember → RDF quads.
 //
-// Emits per-member predicates (multiplicity, is_delimiting) onto the
-// member's concept URI. The member URI is constructed by the caller
-// (typically `gloss-partitive-relation.js`).
+// Emits per-member predicates (presence, count, is_delimiting,
+// derived multiplicity) onto the member's concept URI. The member URI
+// is constructed by the caller (typically `gloss-partitive-relation.js`).
 //
 // Extracted from `gloss-partitive-relation.js` per
 // TODO.partitive-relation-v3/04 so future emitters (a standalone
 // PartitiveMember listing, a stats aggregator) can reuse this
 // emission without modifying the relation emitter (OCP).
+//
+// v4 decomposition: ISO 704:2022 multiplicity is the cross product of
+// two orthogonal dimensions (presence × count). Per the JSON-LD
+// context (`"@type": "@id"`), all three are emitted as URI references
+// into the corresponding SKOS taxonomy namespaces — none as literals.
+//
+//   <member-uri> gloss:presence     <.../presence/required|optional>
+//   <member-uri> gloss:count        <.../count/exactly_one|at_least_one|multiple>
+//   <member-uri> gloss:multiplicity  <.../multiplicity/{ISO name}>   (derived, v3 compat)
+//   <member-uri> gloss:isDelimiting  "true"                           (xsd:boolean)
 
 import { PRED } from './predicates.js';
 import { namedNode, literal, quad } from './terms.js';
 
-// SKOS taxonomy namespace for multiplicity values. concept-model will
-// ship the corresponding taxonomy; until then, the URIs are forward-
-// compatible and resolve once the taxonomy lands.
-//
-// Per the JSON-LD context (`"@type": "@id"`), multiplicity objects
-// MUST be URI references, not string literals. Emitted shape:
-//   <member-uri> gloss:multiplicity <.../multiplicity/compulsory>
+// SKOS taxonomy namespaces (concept-model will ship these taxonomies).
+// Until then, the URIs are forward-compatible and resolve once the
+// taxonomies land.
+export const PRESENCE_NS = 'https://www.glossarist.org/ontologies/presence/';
+export const COUNT_NS = 'https://www.glossarist.org/ontologies/count/';
 export const MULTIPLICITY_NS = 'https://www.glossarist.org/ontologies/multiplicity/';
 
 export function* partitiveMemberToQuads(member, { memberUri }) {
-  if (member?.multiplicity) {
+  if (member?.presence) {
+    yield quad(
+      namedNode(memberUri),
+      namedNode(PRED.gloss.presence),
+      namedNode(PRESENCE_NS + member.presence),
+    );
+  }
+  if (member?.count) {
+    yield quad(
+      namedNode(memberUri),
+      namedNode(PRED.gloss.count),
+      namedNode(COUNT_NS + member.count),
+    );
+  }
+  // Derived multiplicity URI for v3 RDF consumer backward compat.
+  // multiplicity is computed from (presence, count) via the model's
+  // accessor; fall back to the raw field for raw JSON input.
+  const mult = typeof member?.multiplicity === 'string'
+    ? member.multiplicity
+    : null;
+  if (mult) {
     yield quad(
       namedNode(memberUri),
       namedNode(PRED.gloss.multiplicity),
-      namedNode(MULTIPLICITY_NS + member.multiplicity),
+      namedNode(MULTIPLICITY_NS + mult),
     );
   }
   if (member?.is_delimiting === true) {

package/src/rdf/index.d.ts

@@ -121,6 +121,8 @@ export interface PartitiveMemberEmitOptions {
 }
 
 export declare const MULTIPLICITY_NS: string;
+export declare const PRESENCE_NS: string;
+export declare const COUNT_NS: string;
 
 export declare function partitiveMemberToQuads(
   member: PartitiveMember,

package/src/rdf/index.js

@@ -27,7 +27,7 @@ export {
 export { detailedDefinitionToQuads } from './gloss-detailed-definition.js';
 export { conceptSourceToQuads } from './gloss-source.js';
 export { hyperedgeToQuads, hyperedgeSubjectUri } from './gloss-hyperedge.js';
-export { partitiveMemberToQuads, MULTIPLICITY_NS } from './gloss-partitive-member.js';
+export { partitiveMemberToQuads, MULTIPLICITY_NS, PRESENCE_NS, COUNT_NS } from './gloss-partitive-member.js';
 export { partitiveRelationToQuads, partitiveRelationSubjectUri } from './gloss-partitive-relation.js';
 export {
   nonVerbalRepToQuads,

package/src/rdf/predicates.d.ts

@@ -110,6 +110,8 @@ export declare const PRED = {
     "hasPartitiveRelation": "https://www.glossarist.org/ontologies/hasPartitiveRelation",
     "hasPartitive": "https://www.glossarist.org/ontologies/hasPartitive",
     "completeness": "https://www.glossarist.org/ontologies/completeness",
+    "presence": "https://www.glossarist.org/ontologies/presence",
+    "count": "https://www.glossarist.org/ontologies/count",
     "multiplicity": "https://www.glossarist.org/ontologies/multiplicity",
     "isDelimiting": "https://www.glossarist.org/ontologies/isDelimiting",
     "criterion": "https://www.glossarist.org/ontologies/criterion",
@@ -392,6 +394,8 @@ export type Predicate =
   | "https://www.glossarist.org/ontologies/hasPartitiveRelation"
   | "https://www.glossarist.org/ontologies/hasPartitive"
   | "https://www.glossarist.org/ontologies/completeness"
+  | "https://www.glossarist.org/ontologies/presence"
+  | "https://www.glossarist.org/ontologies/count"
   | "https://www.glossarist.org/ontologies/multiplicity"
   | "https://www.glossarist.org/ontologies/isDelimiting"
   | "https://www.glossarist.org/ontologies/criterion"

package/src/rdf/predicates.js

@@ -110,6 +110,8 @@ export const PRED = {
     "hasPartitiveRelation": "https://www.glossarist.org/ontologies/hasPartitiveRelation",
     "hasPartitive": "https://www.glossarist.org/ontologies/hasPartitive",
     "completeness": "https://www.glossarist.org/ontologies/completeness",
+    "presence": "https://www.glossarist.org/ontologies/presence",
+    "count": "https://www.glossarist.org/ontologies/count",
     "multiplicity": "https://www.glossarist.org/ontologies/multiplicity",
     "isDelimiting": "https://www.glossarist.org/ontologies/isDelimiting",
     "criterion": "https://www.glossarist.org/ontologies/criterion",