@lucern/graph-primitives 1.0.16 → 1.0.18

package/dist/invariantEnforcement.js

@@ -74,7 +74,7 @@ function assertBeliefNodeGenericUpdateAllowed(args) {
     throwInvariantError({
       message: "Belief confidence is append-only. Generic node updates cannot set confidence directly.",
       invariantCode: "belief.confidence_append_only",
-      suggestion: "Use epistemicBeliefs.modulateConfidence() so the beliefConfidence ledger and audit trail are updated together.",
+      suggestion: "Use epistemicBeliefs.appendSlScoring() so the beliefConfidence ledger and audit trail are updated together.",
       details: { mutationName: args.mutationName, nodeId: args.node._id }
     });
   }
@@ -126,7 +126,7 @@ function assertBeliefNodeVerifyAllowed(args) {
   throwInvariantError({
     message: "Belief verification cannot set confidence directly. Confidence changes must stay append-only.",
     invariantCode: "belief.confidence_append_only",
-    suggestion: "Call epistemicBeliefs.modulateConfidence() after verification so the confidence history is preserved.",
+    suggestion: "Call epistemicBeliefs.appendSlScoring() after verification so the confidence history is preserved.",
     details: { mutationName: args.mutationName, nodeId: args.node._id }
   });
 }

package/dist/invariantEnforcement.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/beliefLifecycle.ts","../src/invariantEnforcement.ts"],"names":[],"mappings":"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","file":"invariantEnforcement.js","sourcesContent":["/**\n * Belief lifecycle helpers shared across Convex modules.\n *\n * Canonical lifecycle:\n * assumption -> hypothesis -> belief -> fact\n */\n\nexport type BeliefLifecycleStatus =\n  | \"assumption\"\n  | \"hypothesis\"\n  | \"belief\"\n  | \"fact\";\n\ntype PredictionOutcome =\n  | \"pending\"\n  | \"confirmed\"\n  | \"disconfirmed\"\n  | \"partial\"\n  | \"expired\";\n\nconst BELIEF_STATUS_VALUES: readonly BeliefLifecycleStatus[] = [\n  \"assumption\",\n  \"hypothesis\",\n  \"belief\",\n  \"fact\",\n];\n\nconst RESOLVED_PREDICTION_OUTCOMES: readonly PredictionOutcome[] = [\n  \"confirmed\",\n  \"disconfirmed\",\n  \"partial\",\n  \"expired\",\n];\n\nexport function isBeliefLifecycleStatus(\n  value: unknown\n): value is BeliefLifecycleStatus {\n  return (\n    typeof value === \"string\" &&\n    BELIEF_STATUS_VALUES.includes(value as BeliefLifecycleStatus)\n  );\n}\n\nfunction normalizeBeliefConfidence(confidence: unknown): number | null {\n  if (typeof confidence !== \"number\" || !Number.isFinite(confidence)) {\n    return null;\n  }\n  if (confidence >= 0 && confidence <= 1) {\n    return confidence;\n  }\n  // Backward compatibility with historical percentage-scale confidence (0-100).\n  if (confidence > 1 && confidence <= 100) {\n    return confidence / 100;\n  }\n  return null;\n}\n\nexport function isResolvedByConfidence(confidence: unknown): boolean {\n  const normalized = normalizeBeliefConfidence(confidence);\n  if (normalized === null) {\n    return false;\n  }\n  return normalized <= 0 || normalized >= 1;\n}\n\nexport function hasResolvedPredictionOutcome(predictionMeta: unknown): boolean {\n  if (!predictionMeta || typeof predictionMeta !== \"object\") {\n    return false;\n  }\n  const outcome = (predictionMeta as { outcome?: unknown }).outcome;\n  return (\n    typeof outcome === \"string\" &&\n    RESOLVED_PREDICTION_OUTCOMES.includes(outcome as PredictionOutcome)\n  );\n}\n\nfunction getPredictionMetaFromMetadata(\n  metadata: Record<string, unknown> | undefined\n): unknown {\n  return metadata?.predictionMeta;\n}\n\nexport function shouldTreatBeliefAsFact(opts: {\n  confidence?: unknown;\n  predictionMeta?: unknown;\n  metadata?: Record<string, unknown>;\n}): boolean {\n  if (isResolvedByConfidence(opts.confidence)) {\n    return true;\n  }\n  if (hasResolvedPredictionOutcome(opts.predictionMeta)) {\n    return true;\n  }\n  if (\n    hasResolvedPredictionOutcome(getPredictionMetaFromMetadata(opts.metadata))\n  ) {\n    return true;\n  }\n  return false;\n}\n\nexport function resolveBeliefLifecycleStatus(opts: {\n  beliefStatus?: unknown;\n  confidence?: unknown;\n  predictionMeta?: unknown;\n  metadata?: Record<string, unknown>;\n}): BeliefLifecycleStatus {\n  if (shouldTreatBeliefAsFact(opts)) {\n    return \"fact\";\n  }\n\n  const direct = opts.beliefStatus;\n  if (isBeliefLifecycleStatus(direct)) {\n    // If the belief has been scored (has numeric credence) but stored status\n    // is still pre-validation, promote to \"belief\". Scoring = merge to main.\n    const normalized = normalizeBeliefConfidence(opts.confidence);\n    if (normalized !== null && isPreValidationBeliefStatus(direct)) {\n      return \"belief\";\n    }\n    return direct;\n  }\n\n  const metaStatus = opts.metadata?.beliefStatus;\n  if (isBeliefLifecycleStatus(metaStatus)) {\n    const normalized = normalizeBeliefConfidence(opts.confidence);\n    if (normalized !== null && isPreValidationBeliefStatus(metaStatus)) {\n      return \"belief\";\n    }\n    return metaStatus;\n  }\n\n  return \"assumption\";\n}\n\nexport function isPreValidationBeliefStatus(\n  status: BeliefLifecycleStatus\n): boolean {\n  return status === \"assumption\" || status === \"hypothesis\";\n}\n\nexport function isPropagationEligibleBeliefStatus(\n  status: BeliefLifecycleStatus\n): boolean {\n  return status === \"belief\" || status === \"fact\";\n}\n\nexport function promoteBeliefStatusAfterScoring(\n  status: BeliefLifecycleStatus,\n  opts?: {\n    confidence?: unknown;\n    predictionMeta?: unknown;\n    metadata?: Record<string, unknown>;\n  }\n): BeliefLifecycleStatus {\n  if (shouldTreatBeliefAsFact({ ...opts })) {\n    return \"fact\";\n  }\n  if (isPreValidationBeliefStatus(status)) {\n    return \"belief\";\n  }\n  return status === \"fact\" ? \"fact\" : \"belief\";\n}\n","/** Invariant error helpers that protect belief lifecycle mutations. */\nimport { hasResolvedPredictionOutcome } from \"./beliefLifecycle\";\n\ntype StructuredInvariantError = Error & {\n  status: number;\n  code: string;\n  invariantCode?: string;\n  suggestion?: string;\n  details?: unknown;\n};\n\ntype BeliefNodeLike = {\n  _id?: string;\n  nodeType?: unknown;\n  confidence?: unknown;\n  metadata?: unknown;\n  predictionMeta?: unknown;\n};\n\ntype InvariantArgs = {\n  message: string;\n  invariantCode:\n    | \"belief.formulation_immutable_after_scoring\"\n    | \"belief.confidence_append_only\"\n    | \"belief.status_transition_requires_belief_api\"\n    | \"belief.lineage_requires_fork_belief\"\n    | \"belief.hard_delete_forbidden\"\n    | \"entity.create_requires_entity_lifecycle\"\n    | \"entity.update_requires_entity_lifecycle\"\n    | \"entity.archive_requires_entity_lifecycle\"\n    | \"entity.supersede_requires_entity_lifecycle\";\n  suggestion: string;\n  status?: number;\n  code?: string;\n  details?: unknown;\n};\n\nconst FORBIDDEN_GENERIC_BELIEF_METADATA_KEYS = new Set([\n  \"beliefStatus\",\n  \"epistemicStatus\",\n  \"forkedBy\",\n  \"forkedFrom\",\n  \"forkReason\",\n  \"forkTimestamp\",\n  \"status\",\n  \"supersededBy\",\n  \"supersedes\",\n]);\n\nconst ONTOLOGICAL_NODE_TYPES = new Set([\n  \"company\",\n  \"person\",\n  \"investor\",\n  \"function\",\n  \"value_chain\",\n]);\n\nfunction throwInvariantError(args: InvariantArgs): never {\n  const error = new Error(args.message) as StructuredInvariantError;\n  error.status = args.status ?? 409;\n  error.code = args.code ?? \"INVARIANT_VIOLATION\";\n  error.invariantCode = args.invariantCode;\n  error.suggestion = args.suggestion;\n  error.details = args.details;\n  throw error;\n}\n\nexport function isBeliefNode(node: BeliefNodeLike | null | undefined): boolean {\n  return node?.nodeType === \"belief\";\n}\n\nexport function isOntologicalNode(\n  node: BeliefNodeLike | null | undefined\n): boolean {\n  return (\n    typeof node?.nodeType === \"string\" && ONTOLOGICAL_NODE_TYPES.has(node.nodeType)\n  );\n}\n\nexport function isScoredBeliefNode(node: BeliefNodeLike): boolean {\n  if (!isBeliefNode(node)) {\n    return false;\n  }\n\n  const metadata =\n    node.metadata && typeof node.metadata === \"object\"\n      ? (node.metadata as Record<string, unknown>)\n      : undefined;\n\n  const numericConfidence =\n    typeof node.confidence === \"number\" && Number.isFinite(node.confidence);\n  if (numericConfidence) {\n    return true;\n  }\n\n  return (\n    hasResolvedPredictionOutcome(node.predictionMeta) ||\n    hasResolvedPredictionOutcome(metadata?.predictionMeta)\n  );\n}\n\nfunction getForbiddenMetadataKeys(metadata: unknown): string[] {\n  if (!metadata || typeof metadata !== \"object\" || Array.isArray(metadata)) {\n    return [];\n  }\n\n  return Object.keys(metadata).filter((key) =>\n    FORBIDDEN_GENERIC_BELIEF_METADATA_KEYS.has(key)\n  );\n}\n\nexport function assertBeliefNodeGenericUpdateAllowed(args: {\n  node: BeliefNodeLike;\n  updates: Record<string, unknown>;\n  mutationName: string;\n}): void {\n  if (!isBeliefNode(args.node)) {\n    return;\n  }\n\n  if (Object.hasOwn(args.updates, \"confidence\")) {\n    throwInvariantError({\n      message:\n        \"Belief confidence is append-only. Generic node updates cannot set confidence directly.\",\n      invariantCode: \"belief.confidence_append_only\",\n      suggestion:\n        \"Use epistemicBeliefs.modulateConfidence() so the beliefConfidence ledger and audit trail are updated together.\",\n      details: { mutationName: args.mutationName, nodeId: args.node._id },\n    });\n  }\n\n  if (Object.hasOwn(args.updates, \"status\")) {\n    throwInvariantError({\n      message:\n        \"Belief status transitions must use the dedicated belief lifecycle APIs.\",\n      invariantCode: \"belief.status_transition_requires_belief_api\",\n      suggestion:\n        \"Use epistemicBeliefs.updateStatus() or epistemicBeliefs.archive() so status transitions emit the correct audit event.\",\n      details: { mutationName: args.mutationName, nodeId: args.node._id },\n    });\n  }\n\n  const forbiddenMetadataKeys = getForbiddenMetadataKeys(args.updates.metadata);\n  if (forbiddenMetadataKeys.length > 0) {\n    throwInvariantError({\n      message:\n        \"Belief lineage and lifecycle metadata cannot be rewritten through generic node updates.\",\n      invariantCode: \"belief.lineage_requires_fork_belief\",\n      suggestion:\n        \"Use epistemicBeliefs.forkBelief() for lineage changes and dedicated belief lifecycle mutations for status changes.\",\n      details: {\n        mutationName: args.mutationName,\n        nodeId: args.node._id,\n        forbiddenMetadataKeys,\n      },\n    });\n  }\n\n  if (\n    isScoredBeliefNode(args.node) &&\n    (Object.hasOwn(args.updates, \"canonicalText\") ||\n      Object.hasOwn(args.updates, \"contentHash\"))\n  ) {\n    throwInvariantError({\n      message:\n        \"Cannot refine a scored belief in place. Scored formulations are immutable.\",\n      invariantCode: \"belief.formulation_immutable_after_scoring\",\n      suggestion:\n        \"Use epistemicBeliefs.forkBelief() to evolve the formulation while preserving lineage.\",\n      details: { mutationName: args.mutationName, nodeId: args.node._id },\n    });\n  }\n}\n\nexport function assertBeliefNodeArchiveAllowed(args: {\n  node: BeliefNodeLike;\n  mutationName: string;\n}): void {\n  if (!isBeliefNode(args.node)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Belief archiving must go through the dedicated belief lifecycle API.\",\n    invariantCode: \"belief.status_transition_requires_belief_api\",\n    suggestion:\n      \"Use epistemicBeliefs.archive() so the belief lifecycle audit trail stays consistent.\",\n    details: { mutationName: args.mutationName, nodeId: args.node._id },\n  });\n}\n\nexport function assertBeliefNodeVerifyAllowed(args: {\n  node: BeliefNodeLike;\n  confidence: number | undefined;\n  mutationName: string;\n}): void {\n  if (!isBeliefNode(args.node) || args.confidence === undefined) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Belief verification cannot set confidence directly. Confidence changes must stay append-only.\",\n    invariantCode: \"belief.confidence_append_only\",\n    suggestion:\n      \"Call epistemicBeliefs.modulateConfidence() after verification so the confidence history is preserved.\",\n    details: { mutationName: args.mutationName, nodeId: args.node._id },\n  });\n}\n\nexport function assertBeliefNodeSupersedeAllowed(args: {\n  node: BeliefNodeLike;\n  mutationName: string;\n}): void {\n  if (!isBeliefNode(args.node)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Belief lineage changes must use forkBelief(), not the generic supersede path.\",\n    invariantCode: \"belief.lineage_requires_fork_belief\",\n    suggestion:\n      \"Use epistemicBeliefs.forkBelief() so the child belief, supersedes edge, and audit trail are created together.\",\n    details: { mutationName: args.mutationName, nodeId: args.node._id },\n  });\n}\n\nexport function assertBeliefNodeHardDeleteAllowed(args: {\n  node: BeliefNodeLike;\n  allowBeliefHardDelete: boolean;\n  reason: string;\n  mutationName: string;\n}): void {\n  if (!isBeliefNode(args.node)) {\n    return;\n  }\n\n  if (!args.allowBeliefHardDelete) {\n    throwInvariantError({\n      message:\n        \"Belief hard delete is forbidden by default. Beliefs must retain lineage and audit history.\",\n      invariantCode: \"belief.hard_delete_forbidden\",\n      suggestion:\n        \"Use epistemicBeliefs.archive() or epistemicBeliefs.forkBelief() instead. Only migration repair flows may opt into hard delete explicitly.\",\n      details: { mutationName: args.mutationName, nodeId: args.node._id },\n    });\n  }\n\n  if (!args.reason.trim().toLowerCase().startsWith(\"migration:\")) {\n    throwInvariantError({\n      message:\n        \"Belief hard delete bypasses require a migration-scoped rationale.\",\n      invariantCode: \"belief.hard_delete_forbidden\",\n      suggestion:\n        'Retry with allowBeliefHardDelete: true and a reason starting with \"migration:\" only for one-off data repair flows.',\n      details: {\n        mutationName: args.mutationName,\n        nodeId: args.node._id,\n        reason: args.reason,\n      },\n    });\n  }\n}\n\nexport function assertOntologicalNodeGenericCreateAllowed(args: {\n  nodeType: string;\n  mutationName: string;\n}): void {\n  if (!ONTOLOGICAL_NODE_TYPES.has(args.nodeType)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Ontological entities must be created through the dedicated entity lifecycle API.\",\n    invariantCode: \"entity.create_requires_entity_lifecycle\",\n    suggestion:\n      \"Use entityLifecycle.createEntity() so tenant-global canonical scope and deduplication are enforced.\",\n    details: {\n      mutationName: args.mutationName,\n      nodeType: args.nodeType,\n    },\n  });\n}\n\nexport function assertOntologicalNodeGenericUpdateAllowed(args: {\n  node: BeliefNodeLike;\n  mutationName: string;\n}): void {\n  if (!isOntologicalNode(args.node)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Ontological entities must be updated through the dedicated entity lifecycle API.\",\n    invariantCode: \"entity.update_requires_entity_lifecycle\",\n    suggestion:\n      \"Use entityLifecycle.updateEntityAttributes() so canonical entity mutations stay type-safe and audited.\",\n    details: {\n      mutationName: args.mutationName,\n      nodeId: args.node._id,\n      nodeType: args.node.nodeType,\n    },\n  });\n}\n\nexport function assertOntologicalNodeArchiveAllowed(args: {\n  node: BeliefNodeLike;\n  mutationName: string;\n}): void {\n  if (!isOntologicalNode(args.node)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Ontological entities must be archived through the dedicated entity lifecycle API.\",\n    invariantCode: \"entity.archive_requires_entity_lifecycle\",\n    suggestion:\n      \"Use entityLifecycle.archiveEntity() so entity archival emits the correct audit trail and review hooks.\",\n    details: {\n      mutationName: args.mutationName,\n      nodeId: args.node._id,\n      nodeType: args.node.nodeType,\n    },\n  });\n}\n\nexport function assertOntologicalNodeSupersedeAllowed(args: {\n  node: BeliefNodeLike;\n  mutationName: string;\n}): void {\n  if (!isOntologicalNode(args.node)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Ontological entities do not use the generic supersede path.\",\n    invariantCode: \"entity.supersede_requires_entity_lifecycle\",\n    suggestion:\n      \"Use entityLifecycle.updateEntityAttributes() to edit an entity in place or entityLifecycle.mergeEntities() to collapse duplicates.\",\n    details: {\n      mutationName: args.mutationName,\n      nodeId: args.node._id,\n      nodeType: args.node.nodeType,\n    },\n  });\n}\n"]}
+{"version":3,"sources":["../src/beliefLifecycle.ts","../src/invariantEnforcement.ts"],"names":[],"mappings":"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","file":"invariantEnforcement.js","sourcesContent":["/**\n * Belief lifecycle helpers shared across Convex modules.\n *\n * Canonical lifecycle:\n * assumption -> hypothesis -> active -> resolved_true/resolved_false\n *                                \\-> superseded\n */\n\nexport type BeliefLifecycleStatus =\n  | \"assumption\"\n  | \"hypothesis\"\n  | \"active\"\n  | \"superseded\"\n  | \"resolved_true\"\n  | \"resolved_false\";\n\ntype PredictionOutcome =\n  | \"pending\"\n  | \"confirmed\"\n  | \"disconfirmed\"\n  | \"partial\"\n  | \"expired\";\n\nconst BELIEF_STATUS_VALUES: readonly BeliefLifecycleStatus[] = [\n  \"assumption\",\n  \"hypothesis\",\n  \"active\",\n  \"superseded\",\n  \"resolved_true\",\n  \"resolved_false\",\n];\n\nconst RESOLVED_PREDICTION_OUTCOMES: readonly PredictionOutcome[] = [\n  \"confirmed\",\n  \"disconfirmed\",\n  \"partial\",\n  \"expired\",\n];\n\nexport function isBeliefLifecycleStatus(\n  value: unknown\n): value is BeliefLifecycleStatus {\n  return (\n    typeof value === \"string\" &&\n    BELIEF_STATUS_VALUES.includes(value as BeliefLifecycleStatus)\n  );\n}\n\nfunction normalizeLegacyBeliefStatus(\n  value: unknown\n): BeliefLifecycleStatus | null {\n  if (isBeliefLifecycleStatus(value)) {\n    return value;\n  }\n  if (value === \"belief\" || value === \"established\" || value === \"emerging\") {\n    return \"active\";\n  }\n  if (value === \"fact\" || value === \"confirmed\") {\n    return \"resolved_true\";\n  }\n  if (value === \"disconfirmed\" || value === \"expired\") {\n    return \"resolved_false\";\n  }\n  if (value === \"deprecated\") {\n    return \"superseded\";\n  }\n  return null;\n}\n\nfunction normalizeBeliefConfidence(confidence: unknown): number | null {\n  if (typeof confidence !== \"number\" || !Number.isFinite(confidence)) {\n    return null;\n  }\n  if (confidence >= 0 && confidence <= 1) {\n    return confidence;\n  }\n  // Backward compatibility with historical percentage-scale confidence (0-100).\n  if (confidence > 1 && confidence <= 100) {\n    return confidence / 100;\n  }\n  return null;\n}\n\nexport function isResolvedByConfidence(confidence: unknown): boolean {\n  const normalized = normalizeBeliefConfidence(confidence);\n  if (normalized === null) {\n    return false;\n  }\n  return normalized <= 0 || normalized >= 1;\n}\n\nexport function hasResolvedPredictionOutcome(predictionMeta: unknown): boolean {\n  if (!predictionMeta || typeof predictionMeta !== \"object\") {\n    return false;\n  }\n  const outcome = (predictionMeta as { outcome?: unknown }).outcome;\n  return (\n    typeof outcome === \"string\" &&\n    RESOLVED_PREDICTION_OUTCOMES.includes(outcome as PredictionOutcome)\n  );\n}\n\nfunction getPredictionMetaFromMetadata(\n  metadata: Record<string, unknown> | undefined\n): unknown {\n  return metadata?.predictionMeta;\n}\n\nexport function shouldTreatBeliefAsFact(opts: {\n  confidence?: unknown;\n  predictionMeta?: unknown;\n  metadata?: Record<string, unknown>;\n}): boolean {\n  if (isResolvedByConfidence(opts.confidence)) {\n    return true;\n  }\n  if (hasResolvedPredictionOutcome(opts.predictionMeta)) {\n    return true;\n  }\n  if (\n    hasResolvedPredictionOutcome(getPredictionMetaFromMetadata(opts.metadata))\n  ) {\n    return true;\n  }\n  return false;\n}\n\nfunction resolvedPredictionStatus(\n  predictionMeta: unknown\n): BeliefLifecycleStatus | null {\n  if (!predictionMeta || typeof predictionMeta !== \"object\") {\n    return null;\n  }\n  const outcome = (predictionMeta as { outcome?: unknown }).outcome;\n  if (outcome === \"confirmed\") {\n    return \"resolved_true\";\n  }\n  if (outcome === \"disconfirmed\" || outcome === \"expired\") {\n    return \"resolved_false\";\n  }\n  return null;\n}\n\nfunction shouldTreatBeliefAsResolved(opts: {\n  confidence?: unknown;\n  predictionMeta?: unknown;\n  metadata?: Record<string, unknown>;\n}): BeliefLifecycleStatus | null {\n  if (isResolvedByConfidence(opts.confidence)) {\n    const normalized = normalizeBeliefConfidence(opts.confidence);\n    return normalized === 0 ? \"resolved_false\" : \"resolved_true\";\n  }\n  const directPredictionStatus = resolvedPredictionStatus(opts.predictionMeta);\n  if (directPredictionStatus) {\n    return directPredictionStatus;\n  }\n  const metadataPredictionStatus = resolvedPredictionStatus(\n    getPredictionMetaFromMetadata(opts.metadata)\n  );\n  if (metadataPredictionStatus) {\n    return metadataPredictionStatus;\n  }\n  return null;\n}\n\nexport function resolveBeliefLifecycleStatus(opts: {\n  beliefStatus?: unknown;\n  confidence?: unknown;\n  predictionMeta?: unknown;\n  metadata?: Record<string, unknown>;\n}): BeliefLifecycleStatus {\n  const resolvedStatus = shouldTreatBeliefAsResolved(opts);\n  if (resolvedStatus) {\n    return resolvedStatus;\n  }\n\n  const direct = opts.beliefStatus;\n  const normalizedDirect = normalizeLegacyBeliefStatus(direct);\n  if (normalizedDirect) {\n    // If the belief has been scored (has numeric credence) but stored status\n    // is still pre-validation, promote to active. Evidence, not user intent,\n    // makes a hypothesis active.\n    const normalized = normalizeBeliefConfidence(opts.confidence);\n    if (\n      normalized !== null &&\n      isPreValidationBeliefStatus(normalizedDirect)\n    ) {\n      return \"active\";\n    }\n    return normalizedDirect;\n  }\n\n  const metaStatus = opts.metadata?.beliefStatus;\n  const normalizedMetaStatus = normalizeLegacyBeliefStatus(metaStatus);\n  if (normalizedMetaStatus) {\n    const normalized = normalizeBeliefConfidence(opts.confidence);\n    if (\n      normalized !== null &&\n      isPreValidationBeliefStatus(normalizedMetaStatus)\n    ) {\n      return \"active\";\n    }\n    return normalizedMetaStatus;\n  }\n\n  return \"assumption\";\n}\n\nexport function isPreValidationBeliefStatus(\n  status: BeliefLifecycleStatus\n): boolean {\n  return status === \"assumption\" || status === \"hypothesis\";\n}\n\nexport function isPropagationEligibleBeliefStatus(\n  status: BeliefLifecycleStatus\n): boolean {\n  return status === \"active\" || status === \"resolved_true\";\n}\n\nexport function promoteBeliefStatusAfterScoring(\n  status: BeliefLifecycleStatus,\n  opts?: {\n    confidence?: unknown;\n    predictionMeta?: unknown;\n    metadata?: Record<string, unknown>;\n  }\n): BeliefLifecycleStatus {\n  const resolvedStatus = shouldTreatBeliefAsResolved({ ...opts });\n  if (resolvedStatus) {\n    return resolvedStatus;\n  }\n  if (isPreValidationBeliefStatus(status)) {\n    return \"active\";\n  }\n  return status;\n}\n\nexport function promoteBeliefStatusAfterEvidence(\n  status: BeliefLifecycleStatus\n): BeliefLifecycleStatus {\n  return isPreValidationBeliefStatus(status) ? \"active\" : status;\n}\n","/** Invariant error helpers that protect belief lifecycle mutations. */\nimport { hasResolvedPredictionOutcome } from \"./beliefLifecycle\";\n\ntype StructuredInvariantError = Error & {\n  status: number;\n  code: string;\n  invariantCode?: string;\n  suggestion?: string;\n  details?: unknown;\n};\n\ntype BeliefNodeLike = {\n  _id?: string;\n  nodeType?: unknown;\n  confidence?: unknown;\n  metadata?: unknown;\n  predictionMeta?: unknown;\n};\n\ntype InvariantArgs = {\n  message: string;\n  invariantCode:\n    | \"belief.formulation_immutable_after_scoring\"\n    | \"belief.confidence_append_only\"\n    | \"belief.status_transition_requires_belief_api\"\n    | \"belief.lineage_requires_fork_belief\"\n    | \"belief.hard_delete_forbidden\"\n    | \"entity.create_requires_entity_lifecycle\"\n    | \"entity.update_requires_entity_lifecycle\"\n    | \"entity.archive_requires_entity_lifecycle\"\n    | \"entity.supersede_requires_entity_lifecycle\";\n  suggestion: string;\n  status?: number;\n  code?: string;\n  details?: unknown;\n};\n\nconst FORBIDDEN_GENERIC_BELIEF_METADATA_KEYS = new Set([\n  \"beliefStatus\",\n  \"epistemicStatus\",\n  \"forkedBy\",\n  \"forkedFrom\",\n  \"forkReason\",\n  \"forkTimestamp\",\n  \"status\",\n  \"supersededBy\",\n  \"supersedes\",\n]);\n\nconst ONTOLOGICAL_NODE_TYPES = new Set([\n  \"company\",\n  \"person\",\n  \"investor\",\n  \"function\",\n  \"value_chain\",\n]);\n\nfunction throwInvariantError(args: InvariantArgs): never {\n  const error = new Error(args.message) as StructuredInvariantError;\n  error.status = args.status ?? 409;\n  error.code = args.code ?? \"INVARIANT_VIOLATION\";\n  error.invariantCode = args.invariantCode;\n  error.suggestion = args.suggestion;\n  error.details = args.details;\n  throw error;\n}\n\nexport function isBeliefNode(node: BeliefNodeLike | null | undefined): boolean {\n  return node?.nodeType === \"belief\";\n}\n\nexport function isOntologicalNode(\n  node: BeliefNodeLike | null | undefined\n): boolean {\n  return (\n    typeof node?.nodeType === \"string\" && ONTOLOGICAL_NODE_TYPES.has(node.nodeType)\n  );\n}\n\nexport function isScoredBeliefNode(node: BeliefNodeLike): boolean {\n  if (!isBeliefNode(node)) {\n    return false;\n  }\n\n  const metadata =\n    node.metadata && typeof node.metadata === \"object\"\n      ? (node.metadata as Record<string, unknown>)\n      : undefined;\n\n  const numericConfidence =\n    typeof node.confidence === \"number\" && Number.isFinite(node.confidence);\n  if (numericConfidence) {\n    return true;\n  }\n\n  return (\n    hasResolvedPredictionOutcome(node.predictionMeta) ||\n    hasResolvedPredictionOutcome(metadata?.predictionMeta)\n  );\n}\n\nfunction getForbiddenMetadataKeys(metadata: unknown): string[] {\n  if (!metadata || typeof metadata !== \"object\" || Array.isArray(metadata)) {\n    return [];\n  }\n\n  return Object.keys(metadata).filter((key) =>\n    FORBIDDEN_GENERIC_BELIEF_METADATA_KEYS.has(key)\n  );\n}\n\nexport function assertBeliefNodeGenericUpdateAllowed(args: {\n  node: BeliefNodeLike;\n  updates: Record<string, unknown>;\n  mutationName: string;\n}): void {\n  if (!isBeliefNode(args.node)) {\n    return;\n  }\n\n  if (Object.hasOwn(args.updates, \"confidence\")) {\n    throwInvariantError({\n      message:\n        \"Belief confidence is append-only. Generic node updates cannot set confidence directly.\",\n      invariantCode: \"belief.confidence_append_only\",\n      suggestion:\n        \"Use epistemicBeliefs.appendSlScoring() so the beliefConfidence ledger and audit trail are updated together.\",\n      details: { mutationName: args.mutationName, nodeId: args.node._id },\n    });\n  }\n\n  if (Object.hasOwn(args.updates, \"status\")) {\n    throwInvariantError({\n      message:\n        \"Belief status transitions must use the dedicated belief lifecycle APIs.\",\n      invariantCode: \"belief.status_transition_requires_belief_api\",\n      suggestion:\n        \"Use epistemicBeliefs.updateStatus() or epistemicBeliefs.archive() so status transitions emit the correct audit event.\",\n      details: { mutationName: args.mutationName, nodeId: args.node._id },\n    });\n  }\n\n  const forbiddenMetadataKeys = getForbiddenMetadataKeys(args.updates.metadata);\n  if (forbiddenMetadataKeys.length > 0) {\n    throwInvariantError({\n      message:\n        \"Belief lineage and lifecycle metadata cannot be rewritten through generic node updates.\",\n      invariantCode: \"belief.lineage_requires_fork_belief\",\n      suggestion:\n        \"Use epistemicBeliefs.forkBelief() for lineage changes and dedicated belief lifecycle mutations for status changes.\",\n      details: {\n        mutationName: args.mutationName,\n        nodeId: args.node._id,\n        forbiddenMetadataKeys,\n      },\n    });\n  }\n\n  if (\n    isScoredBeliefNode(args.node) &&\n    (Object.hasOwn(args.updates, \"canonicalText\") ||\n      Object.hasOwn(args.updates, \"contentHash\"))\n  ) {\n    throwInvariantError({\n      message:\n        \"Cannot refine a scored belief in place. Scored formulations are immutable.\",\n      invariantCode: \"belief.formulation_immutable_after_scoring\",\n      suggestion:\n        \"Use epistemicBeliefs.forkBelief() to evolve the formulation while preserving lineage.\",\n      details: { mutationName: args.mutationName, nodeId: args.node._id },\n    });\n  }\n}\n\nexport function assertBeliefNodeArchiveAllowed(args: {\n  node: BeliefNodeLike;\n  mutationName: string;\n}): void {\n  if (!isBeliefNode(args.node)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Belief archiving must go through the dedicated belief lifecycle API.\",\n    invariantCode: \"belief.status_transition_requires_belief_api\",\n    suggestion:\n      \"Use epistemicBeliefs.archive() so the belief lifecycle audit trail stays consistent.\",\n    details: { mutationName: args.mutationName, nodeId: args.node._id },\n  });\n}\n\nexport function assertBeliefNodeVerifyAllowed(args: {\n  node: BeliefNodeLike;\n  confidence: number | undefined;\n  mutationName: string;\n}): void {\n  if (!isBeliefNode(args.node) || args.confidence === undefined) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Belief verification cannot set confidence directly. Confidence changes must stay append-only.\",\n    invariantCode: \"belief.confidence_append_only\",\n    suggestion:\n      \"Call epistemicBeliefs.appendSlScoring() after verification so the confidence history is preserved.\",\n    details: { mutationName: args.mutationName, nodeId: args.node._id },\n  });\n}\n\nexport function assertBeliefNodeSupersedeAllowed(args: {\n  node: BeliefNodeLike;\n  mutationName: string;\n}): void {\n  if (!isBeliefNode(args.node)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Belief lineage changes must use forkBelief(), not the generic supersede path.\",\n    invariantCode: \"belief.lineage_requires_fork_belief\",\n    suggestion:\n      \"Use epistemicBeliefs.forkBelief() so the child belief, supersedes edge, and audit trail are created together.\",\n    details: { mutationName: args.mutationName, nodeId: args.node._id },\n  });\n}\n\nexport function assertBeliefNodeHardDeleteAllowed(args: {\n  node: BeliefNodeLike;\n  allowBeliefHardDelete: boolean;\n  reason: string;\n  mutationName: string;\n}): void {\n  if (!isBeliefNode(args.node)) {\n    return;\n  }\n\n  if (!args.allowBeliefHardDelete) {\n    throwInvariantError({\n      message:\n        \"Belief hard delete is forbidden by default. Beliefs must retain lineage and audit history.\",\n      invariantCode: \"belief.hard_delete_forbidden\",\n      suggestion:\n        \"Use epistemicBeliefs.archive() or epistemicBeliefs.forkBelief() instead. Only migration repair flows may opt into hard delete explicitly.\",\n      details: { mutationName: args.mutationName, nodeId: args.node._id },\n    });\n  }\n\n  if (!args.reason.trim().toLowerCase().startsWith(\"migration:\")) {\n    throwInvariantError({\n      message:\n        \"Belief hard delete bypasses require a migration-scoped rationale.\",\n      invariantCode: \"belief.hard_delete_forbidden\",\n      suggestion:\n        'Retry with allowBeliefHardDelete: true and a reason starting with \"migration:\" only for one-off data repair flows.',\n      details: {\n        mutationName: args.mutationName,\n        nodeId: args.node._id,\n        reason: args.reason,\n      },\n    });\n  }\n}\n\nexport function assertOntologicalNodeGenericCreateAllowed(args: {\n  nodeType: string;\n  mutationName: string;\n}): void {\n  if (!ONTOLOGICAL_NODE_TYPES.has(args.nodeType)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Ontological entities must be created through the dedicated entity lifecycle API.\",\n    invariantCode: \"entity.create_requires_entity_lifecycle\",\n    suggestion:\n      \"Use entityLifecycle.createEntity() so tenant-global canonical scope and deduplication are enforced.\",\n    details: {\n      mutationName: args.mutationName,\n      nodeType: args.nodeType,\n    },\n  });\n}\n\nexport function assertOntologicalNodeGenericUpdateAllowed(args: {\n  node: BeliefNodeLike;\n  mutationName: string;\n}): void {\n  if (!isOntologicalNode(args.node)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Ontological entities must be updated through the dedicated entity lifecycle API.\",\n    invariantCode: \"entity.update_requires_entity_lifecycle\",\n    suggestion:\n      \"Use entityLifecycle.updateEntityAttributes() so canonical entity mutations stay type-safe and audited.\",\n    details: {\n      mutationName: args.mutationName,\n      nodeId: args.node._id,\n      nodeType: args.node.nodeType,\n    },\n  });\n}\n\nexport function assertOntologicalNodeArchiveAllowed(args: {\n  node: BeliefNodeLike;\n  mutationName: string;\n}): void {\n  if (!isOntologicalNode(args.node)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Ontological entities must be archived through the dedicated entity lifecycle API.\",\n    invariantCode: \"entity.archive_requires_entity_lifecycle\",\n    suggestion:\n      \"Use entityLifecycle.archiveEntity() so entity archival emits the correct audit trail and review hooks.\",\n    details: {\n      mutationName: args.mutationName,\n      nodeId: args.node._id,\n      nodeType: args.node.nodeType,\n    },\n  });\n}\n\nexport function assertOntologicalNodeSupersedeAllowed(args: {\n  node: BeliefNodeLike;\n  mutationName: string;\n}): void {\n  if (!isOntologicalNode(args.node)) {\n    return;\n  }\n\n  throwInvariantError({\n    message:\n      \"Ontological entities do not use the generic supersede path.\",\n    invariantCode: \"entity.supersede_requires_entity_lifecycle\",\n    suggestion:\n      \"Use entityLifecycle.updateEntityAttributes() to edit an entity in place or entityLifecycle.mergeEntities() to collapse duplicates.\",\n    details: {\n      mutationName: args.mutationName,\n      nodeId: args.node._id,\n      nodeType: args.node.nodeType,\n    },\n  });\n}\n"]}

package/dist/proof-attestation.json

@@ -31,15 +31,15 @@
     }
   ],
   "contractsCovered": [
+    "append_sl_scoring",
     "create_evidence",
     "list_beliefs",
-    "list_tasks",
-    "modulate_confidence"
+    "list_tasks"
   ],
   "emittersUsed": [
     "typescript-types",
     "convex-validators",
     "proof-attestation"
   ],
-  "signedAt": 1780319797871
+  "signedAt": 1780432543399
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucern/graph-primitives",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -32,9 +32,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@lucern/access-control": "1.0.16",
-    "@lucern/confidence": "1.0.16",
-    "@lucern/contracts": "1.0.16",
+    "@lucern/access-control": "1.0.18",
+    "@lucern/confidence": "1.0.18",
+    "@lucern/contracts": "1.0.18",
     "convex": "^1.39.1"
   },
   "devDependencies": {

package/dist/globalId-DKh9d_uD.d.ts

@@ -1,20 +0,0 @@
-/**
- * Shared UUID v4 generator for global IDs.
- *
- * Uses crypto.getRandomValues() for collision-safe generation.
- * Replaces the Math.random()-based UUID pattern that was duplicated
- * across 7+ files.
- *
- * @module convex/lib/globalId
- */
-/**
- * Generate a UUID v4 global ID using crypto-safe random bytes.
- */
-declare function generateGlobalId(): string;
-
-declare const globalId_generateGlobalId: typeof generateGlobalId;
-declare namespace globalId {
-  export { globalId_generateGlobalId as generateGlobalId };
-}
-
-export { generateGlobalId as a, globalId as g };