feat(v2): implement Canonical Model and Provider SPI (Sub-Project 1)

.gitignore

@@ -15,3 +15,5 @@ claude-export/
 !ui/public/opencontext-logo.png
 !ui/public/dark-logo-aviskaar.png
 0532b8293bb107be5c0c20f3e2980f09107f44de9a58414157f5bed3f7ef0d19*/
+
+.worktrees/

package.json

@@ -4,12 +4,15 @@
   "description": "Convert ChatGPT conversation exports to Claude-compatible format",
   "main": "dist/index.js",
   "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
   "bin": {
     "opencontext": "./dist/index.js",
     "opencontext-mcp": "./dist/mcp/index.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "npm --workspaces --if-present run build && tsc",
     "start": "tsx src/index.ts",
     "dev": "tsx watch src/index.ts",
     "server": "tsx src/server.ts",

packages/core/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@opencontext/core",
+  "version": "2.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8"
+  }
+}

packages/core/src/identity/hash.ts

@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+
+function canonicalizeJson(obj: unknown): string {
+  if (obj === null || typeof obj !== 'object') {
+    return JSON.stringify(obj);
+  }
+  if (Array.isArray(obj)) {
+    return `[${obj.map(canonicalizeJson).join(',')}]`;
+  }
+  const keys = Object.keys(obj as Record<string, unknown>).sort();
+  const pairs = keys.map((k) => `${JSON.stringify(k)}:${canonicalizeJson((obj as Record<string, unknown>)[k])}`);
+  return `{${pairs.join(',')}}`;
+}
+
+export function computeContentHash(content: string | Record<string, unknown>): string {
+  const serialized = typeof content === 'string' ? content : canonicalizeJson(content);
+  return createHash('sha256').update(serialized, 'utf8').digest('hex');
+}

packages/core/src/identity/index.ts

@@ -0,0 +1,2 @@
+export * from './ulid.js';
+export * from './hash.js';

packages/core/src/identity/ulid.ts

@@ -0,0 +1,41 @@
+import { randomBytes } from 'node:crypto';
+
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+let lastTime = 0;
+const lastRandom: number[] = new Array(16).fill(0);
+
+export function generateUlid(seedTime: number = Date.now()): string {
+  let time = seedTime;
+  if (time <= lastTime) {
+    time = lastTime;
+    // Increment last random for strict monotonicity within same millisecond
+    for (let i = 15; i >= 0; i--) {
+      if (lastRandom[i] < 31) {
+        lastRandom[i]++;
+        break;
+      }
+      lastRandom[i] = 0;
+    }
+  } else {
+    lastTime = time;
+    const buf = randomBytes(16);
+    for (let i = 0; i < 16; i++) {
+      lastRandom[i] = buf[i] % 32;
+    }
+  }
+
+  // 10 chars for 48-bit timestamp
+  let timeStr = '';
+  for (let i = 9; i >= 0; i--) {
+    timeStr = ENCODING[time % 32] + timeStr;
+    time = Math.floor(time / 32);
+  }
+
+  // 16 chars for 80-bit randomness
+  let randStr = '';
+  for (let i = 0; i < 16; i++) {
+    randStr += ENCODING[lastRandom[i]];
+  }
+
+  return timeStr + randStr;
+}

packages/core/src/index.ts

@@ -0,0 +1,6 @@
+export * from './model/types.js';
+export * from './model/factory.js';
+export * from './identity/index.js';
+export * from './shims/v1-shim.js';
+export const VERSION = '2.0.0';
+

packages/core/src/model/factory.ts

@@ -0,0 +1,53 @@
+import { CanonicalContext, ContextType, ScopeId, NamespaceId, LifecycleState } from './types.js';
+import { generateUlid } from '../identity/ulid.js';
+import { computeContentHash } from '../identity/hash.js';
+
+export interface CreateContextOptions {
+  id?: string;
+  namespace?: NamespaceId;
+  scope?: ScopeId;
+  type?: ContextType;
+  lifecycle?: LifecycleState;
+  content: {
+    text?: string;
+    structured?: Record<string, unknown>;
+    mediaType?: string;
+    embedding?: number[];
+  };
+  metadata?: Record<string, unknown>;
+  actor?: 'user' | 'agent' | 'system' | 'integration';
+  agentId?: string;
+  sourceUri?: string;
+  relationships?: CanonicalContext['relationships'];
+  expiresAt?: string;
+}
+
+export function createCanonicalContext(opts: CreateContextOptions): CanonicalContext {
+  const now = new Date().toISOString();
+  const hashInput = opts.content.text ?? opts.content.structured ?? {};
+
+  return {
+    id: opts.id ?? generateUlid(),
+    namespace: opts.namespace ?? 'default',
+    scope: opts.scope ?? 'global',
+    type: opts.type ?? 'fact',
+    content: opts.content,
+    metadata: opts.metadata ?? {},
+    provenance: {
+      actor: opts.actor ?? 'user',
+      agentId: opts.agentId,
+      sourceUri: opts.sourceUri,
+      contentHash: computeContentHash(hashInput),
+    },
+    relationships: opts.relationships ?? [],
+    timestamps: {
+      createdAt: now,
+      updatedAt: now,
+      expiresAt: opts.expiresAt,
+    },
+    version: {
+      revision: 1,
+    },
+    lifecycle: opts.lifecycle ?? 'active',
+  };
+}

packages/core/src/model/types.ts

@@ -0,0 +1,63 @@
+export type ContextId = string;
+export type NamespaceId = string;
+export type ScopeId = string;
+
+export type ContextType =
+  | 'message'
+  | 'fact'
+  | 'decision'
+  | 'constraint'
+  | 'preference'
+  | 'artifact'
+  | 'observation'
+  | 'tool_result'
+  | 'summary'
+  | 'checkpoint'
+  | (string & {});
+
+export type LifecycleState = 'active' | 'archived' | 'deprecated' | 'soft_deleted' | 'pinned';
+
+export interface RelationshipEdge {
+  targetId: ContextId;
+  relation: 'supersedes' | 'derived_from' | 'references' | 'child_of' | 'caused_by' | string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ContextProvenance {
+  actor: 'user' | 'agent' | 'system' | 'integration';
+  agentId?: string;
+  model?: string;
+  sourceUri?: string;
+  signature?: string;
+  contentHash: string;
+  derivationChain?: ContextId[];
+}
+
+export interface ContextTimestamps {
+  createdAt: string;
+  updatedAt: string;
+  accessedAt?: string;
+  expiresAt?: string;
+}
+
+export interface CanonicalContext {
+  id: ContextId;
+  namespace: NamespaceId;
+  scope: ScopeId;
+  type: ContextType;
+  content: {
+    text?: string;
+    structured?: Record<string, unknown>;
+    mediaType?: string;
+    embedding?: number[];
+  };
+  metadata: Record<string, unknown>;
+  provenance: ContextProvenance;
+  relationships: RelationshipEdge[];
+  timestamps: ContextTimestamps;
+  version: {
+    revision: number;
+    clock?: Record<string, number>;
+  };
+  lifecycle: LifecycleState;
+}