id: meta-log-db-readme title: "Meta-Log Database Package" level: foundational type: documentation tags: [meta-log-db, readme, package-overview, installation, usage] keywords: [meta-log-db, prolog, datalog, r5rs, sparql, shacl, canvasl, npm-package] prerequisites: [] enables: [meta-log-db-installation, meta-log-db-usage] related: [meta-log-db-rfc2119-specification, glossary, canvasl-metaverse-browser-api] readingTime: 15 difficulty: 1 version: "1.2.0" gitTag: "v1.2.0" blackboard: status: active assignedAgent: "meta-log-db-documentation-agent" lastUpdate: "2025-01-17" dependencies: [] watchers: []

Meta-Log Database Package

A native npm package providing core database functionality for ProLog, DataLog, and R5RS integration. This package can be npm linked into both OpenCode and Obsidian plugins to provide a common database interface.

Overview

The Meta-Log Database package (meta-log-db) provides:

• ProLog Engine - Logic programming with unification and resolution
• DataLog Engine - Fact extraction and bottom-up evaluation
• R5RS Integration - Function registry and execution
• JSONL/CanvasL Parser - File format parsing and fact extraction
• RDF/SPARQL Support - Triple storage and SPARQL queries
• SHACL Validation - Shape constraint validation

Extensions (v1.2.0)

The following extensions are available as optional modules. All extensions are disabled by default for backward compatibility.

Chain Complex & Homology

Algebraic topology validation with ∂² = 0 property checking:

const db = new MetaLogDb({
  enableHomology: true
});

const complex: ChainComplex = {
  C0: [{ id: 'v1', dim: 0, boundary: [], data: {} }],
  C1: [{ id: 'e1', dim: 1, boundary: ['v1', 'v2'], data: {} }],
  C2: [],
  C3: [],
  C4: [],
  ∂: new Map([['e1', ['v1', 'v2']]])
};

const result = db.validateHomology(complex);
console.log(`Valid: ${result.valid}, Betti numbers: ${result.betti}`);

MetaLogNode

Atemporal DAG node structure with cryptographic identity:

import { MetaLogNodeManager } from 'meta-log-db/extensions/metalog-node';

const manager = new MetaLogNodeManager();
const node = await manager.createNode({
  content: {
    topo: { type: 'Topology', objects: {}, arcs: [] },
    geo: { type: 'FeatureCollection', features: [] }
  },
  parent: 'genesis'
});

const isValid = await manager.verifyNode(node);

Projective/Affine Geometry

Coordinate system transformations:

import { ProjectiveAffineConverter } from 'meta-log-db/extensions/geometry';

const converter = new ProjectiveAffineConverter();
const projective = converter.affineToProjective({ x: 1, y: 2 });
const affine = converter.projectiveToAffine({ x: 1, y: 2, z: 0, w: 1 });

DAG Operations

Directed Acyclic Graph management:

import { DAGManager } from 'meta-log-db/extensions/dag';

const manager = new DAGManager(dag);
const lca = manager.findLCA('cid1', 'cid2');
const children = manager.getChildren('cid1');
const ancestors = manager.getAncestors('cid1');

Org Mode R5RS Functions

Org Mode document parsing:

const db = new MetaLogDb({
  enableOrgMode: true
});

// Via R5RS functions
const ast = await db.executeR5RS('r5rs:parse-org-document', [orgContent]);
const headings = await db.executeR5RS('r5rs:extract-headings', [orgContent]);
const blocks = await db.executeR5RS('r5rs:extract-source-blocks', [orgContent]);

Installation

From npm

npm install meta-log-db

From Source

git clone https://github.com/bthornemail/meta-log-db.git
cd meta-log-db
npm install
npm run build
npm link

Usage

import { MetaLogDb } from 'meta-log-db';

const db = new MetaLogDb({
  r5rsEnginePath: './r5rs-canvas-engine.scm',
  enableProlog: true,
  enableDatalog: true,
  enableRdf: true,
  enableShacl: true,
  // Extensions (optional)
  enableHomology: true,
  enableMetaLogNode: true,
  enableProjectiveAffine: true,
  enableDAG: true,
  enableOrgMode: true
});

// Load JSONL canvas
await db.loadCanvas('automaton-kernel.jsonl');

// Extract facts
const facts = db.extractFacts();

// ProLog query
const results = await db.prologQuery('(node ?Id ?Type)');

// DataLog query
const datalogResults = await db.datalogQuery('(missing_implementation ?N)');

// SPARQL query
const sparqlResults = await db.sparqlQuery(`
  SELECT ?id ?type WHERE {
    ?id rdf:type ?type
  }
`);

// SHACL validation
const validation = await db.validateShacl();

Documentation

Specification

• RFC2119 Specification - Complete package specification with MUST/SHOULD/MAY requirements
• Glossary - Key terms and concepts

Guides

• CanvasL Metaverse Browser API - Complete browser API documentation
• Migration Guide - Migrating from MetaLogBrowserAdapter

Examples

• Real-World Examples - Practical usage examples
• R5RS Examples - R5RS Scheme parser examples
• SHACL Examples - SHACL validation examples
• SPARQL Examples - SPARQL query examples

Reference

• Frontmatter Validation Setup - TypeScript configuration for frontmatter validation
• Linking Setup - npm link setup guide
• Testing Guide - Testing guide for CanvasL Metaverse Browser

Development

# Build (Node.js)
npm run build

# Build browser bundle
npm run build:browser

# Build all (Node.js + browser)
npm run build:all

# Verify browser build
npm run verify:browser

# Watch mode
npm run watch

# Test
npm test

Browser Usage

For browser environments, use the unified CanvasLMetaverseBrowser:

import { CanvasLMetaverseBrowser } from 'meta-log-db/browser';

const browser = new CanvasLMetaverseBrowser({
  enableProlog: true,
  enableDatalog: true,
  enableRdf: true,
  enableShacl: true,
  cacheStrategy: 'both', // Use both memory and IndexedDB cache
  indexedDBName: 'meta-log-db',
  // Extensions (optional)
  enableHomology: true,
  enableMetaLogNode: true,
  enableProjectiveAffine: true,
  enableDAG: true,
  enableOrgMode: true
});

// Initialize (sets up IndexedDB, file I/O, etc.)
await browser.init();

// Load canvas from URL (path is identifier, url is fetch location)
await browser.loadCanvas('automaton-kernel.jsonl', '/jsonl/automaton-kernel.jsonl');

// Use same API as Node.js version
const facts = browser.extractFacts();
const results = await browser.prologQuery('(node ?Id ?Type)');

// Execute CanvasL objects
const canvaslResult = await browser.executeCanvasLObject({
  type: 'r5rs-call',
  function: 'r5rs:church-add',
  args: [2, 3]
});

CanvasL Object Execution

CanvasLMetaverseBrowser provides unified CanvasL object execution:

// Execute single CanvasL object
const result = await browser.executeCanvasLObject({
  type: 'rdf-triple',
  subject: 'http://example.org/s',
  predicate: 'http://example.org/p',
  object: 'http://example.org/o'
});

// Execute multiple CanvasL objects
const results = await browser.executeCanvasLObjects([
  { type: 'rdf-triple', subject: '...', predicate: '...', object: '...' },
  { type: 'slide', id: 'slide-1', dimension: '0D' },
  { type: 'r5rs-call', function: 'r5rs:church-add', args: [2, 3] }
]);

Supported CanvasL object types:

• rdf-triple - Add RDF triple to store
• r5rs-call - Execute R5RS function
• sparql-construct - Execute SPARQL CONSTRUCT query
• prolog-query - Execute ProLog query
• datalog-query - Execute DataLog query
• shacl-validate - Validate with SHACL
• slide - Return slide object as-is

Legacy Browser API

For backward compatibility, MetaLogDbBrowser is still available:

import { MetaLogDbBrowser } from 'meta-log-db/browser';

const db = new MetaLogDbBrowser({ /* config */ });
await db.init();
await db.loadCanvas('path', 'url');

Linking to Plugins

# Link meta-log-db
cd meta-log-db
npm link

# Use in OpenCode plugin
cd .opencode
npm link meta-log-db

# Use in Obsidian plugin
cd .obsidian/plugins/universal-life-protocol-plugin
npm link meta-log-db

Package Information

• Package Name: meta-log-db
• Version: 1.2.0
• License: MIT
• Node Version: >=18.0.0
• Repository: https://github.com/bthornemail/meta-log-db

License

MIT