@aletheia-labs/core 0.1.0

package/dist/types/primitives.js

@@ -0,0 +1,42 @@
+/**
+ * Primitive value objects shared across all domain types.
+ *
+ * All identifiers are zod-branded strings: at runtime a `MemoryId` and an
+ * `EventId` are both strings; TypeScript enforces nominal separation so they
+ * cannot be mixed. The single source of truth is the zod schema — types are
+ * derived from it via `z.infer`.
+ */
+import { z } from 'zod';
+// -- Branded IDs (one brand system: zod) -------------------------------------
+const idShape = z.string().min(1).max(256);
+export const MemoryIdSchema = idShape.brand();
+export const EventIdSchema = idShape.brand();
+export const ProposalIdSchema = idShape.brand();
+export const ConflictIdSchema = idShape.brand();
+export const AgentIdSchema = idShape.brand();
+export const SourceArtifactIdSchema = idShape.brand();
+export const ReceiptIdSchema = idShape.brand();
+// -- Timestamps --------------------------------------------------------------
+/** ISO-8601 UTC timestamp. We never accept partial dates or local timezones. */
+export const IsoTimestampSchema = z
+    .string()
+    .datetime({ offset: false, message: 'must be ISO-8601 in UTC (e.g. 2026-05-16T12:00:00Z)' });
+// -- Hash digests ------------------------------------------------------------
+/**
+ * Content digest of a source artifact. We accept any well-formed hex hash
+ * (sha256, blake3, etc.) — the algorithm is implicit in the lane that produced it.
+ */
+export const HashDigestSchema = z
+    .string()
+    .regex(/^[a-f0-9]{32,128}$/i, 'must be a hex digest between 32 and 128 chars');
+// -- Source paths / lanes ----------------------------------------------------
+/**
+ * Path or registry lane to the source artifact. NOT prose: must be resolvable
+ * to a real artifact by the source-lane resolver.
+ */
+export const SourcePathSchema = z
+    .string()
+    .min(1)
+    .max(1024)
+    .refine((s) => !s.includes('\n'), 'source path cannot contain newlines');
+//# sourceMappingURL=primitives.js.map

package/dist/types/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../../src/types/primitives.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+EAA+E;AAE/E,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE3C,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC,KAAK,EAAc,CAAC;AAG1D,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,EAAa,CAAC;AAGxD,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,KAAK,EAAgB,CAAC;AAG9D,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,KAAK,EAAgB,CAAC;AAG9D,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,EAAa,CAAC;AAGxD,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC,KAAK,EAAsB,CAAC;AAG1E,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC,KAAK,EAAe,CAAC;AAG5D,+EAA+E;AAE/E,gFAAgF;AAChF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,EAAE;KACR,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,qDAAqD,EAAE,CAAC,CAAC;AAG/F,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,EAAE;KACR,KAAK,CAAC,qBAAqB,EAAE,+CAA+C,CAAC,CAAC;AAGjF,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,IAAI,CAAC;KACT,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,qCAAqC,CAAC,CAAC"}

package/dist/types/status-transitions.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Allowed status transitions for a MemoryAtom.
+ *
+ * Phase 1 matrix is intentionally strict; Phase 2 (memory dynamics) will
+ * relax some terminal states via reconsolidation events.
+ *
+ * Sealed is terminal-from-without — only an authorized operator can move
+ * a sealed atom, and that path doesn't go through `transitionStatus`.
+ */
+import type { MemoryStatus } from './enums.js';
+/**
+ * Check whether moving from `from` to `to` is a valid transition.
+ *
+ * Returns `true` for legal transitions and `false` for illegal ones.
+ * Does NOT consider permissions, evidence, or conflicts — those are the
+ * caller's responsibility (typically the WriteGate or MemoryStore wrapper).
+ */
+export declare function isAllowedTransition(from: MemoryStatus, to: MemoryStatus): boolean;
+/**
+ * Get the set of statuses an atom can legally transition to from `from`.
+ */
+export declare function allowedTransitionsFrom(from: MemoryStatus): ReadonlySet<MemoryStatus>;
+//# sourceMappingURL=status-transitions.d.ts.map

package/dist/types/status-transitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-transitions.d.ts","sourceRoot":"","sources":["../../src/types/status-transitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAyB/C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,GAAG,OAAO,CAEjF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,CAAC,YAAY,CAAC,CAEpF"}

package/dist/types/status-transitions.js

@@ -0,0 +1,48 @@
+/**
+ * Allowed status transitions for a MemoryAtom.
+ *
+ * Phase 1 matrix is intentionally strict; Phase 2 (memory dynamics) will
+ * relax some terminal states via reconsolidation events.
+ *
+ * Sealed is terminal-from-without — only an authorized operator can move
+ * a sealed atom, and that path doesn't go through `transitionStatus`.
+ */
+const TRANSITIONS = {
+    candidate: new Set([
+        'verified',
+        'deprecated',
+        'rejected',
+        'sealed',
+        'human_required',
+    ]),
+    verified: new Set([
+        'trusted',
+        'deprecated',
+        'rejected',
+        'sealed',
+        'human_required',
+    ]),
+    trusted: new Set(['deprecated', 'rejected', 'sealed']),
+    deprecated: new Set(['verified', 'rejected']),
+    rejected: new Set(),
+    // Sealed has no outward transitions through this API. Special path required.
+    sealed: new Set(),
+    human_required: new Set(['candidate', 'verified', 'rejected']),
+};
+/**
+ * Check whether moving from `from` to `to` is a valid transition.
+ *
+ * Returns `true` for legal transitions and `false` for illegal ones.
+ * Does NOT consider permissions, evidence, or conflicts — those are the
+ * caller's responsibility (typically the WriteGate or MemoryStore wrapper).
+ */
+export function isAllowedTransition(from, to) {
+    return TRANSITIONS[from].has(to);
+}
+/**
+ * Get the set of statuses an atom can legally transition to from `from`.
+ */
+export function allowedTransitionsFrom(from) {
+    return TRANSITIONS[from];
+}
+//# sourceMappingURL=status-transitions.js.map

package/dist/types/status-transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-transitions.js","sourceRoot":"","sources":["../../src/types/status-transitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,GAA8D;IAC7E,SAAS,EAAE,IAAI,GAAG,CAAe;QAC/B,UAAU;QACV,YAAY;QACZ,UAAU;QACV,QAAQ;QACR,gBAAgB;KACjB,CAAC;IACF,QAAQ,EAAE,IAAI,GAAG,CAAe;QAC9B,SAAS;QACT,YAAY;QACZ,UAAU;QACV,QAAQ;QACR,gBAAgB;KACjB,CAAC;IACF,OAAO,EAAE,IAAI,GAAG,CAAe,CAAC,YAAY,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;IACpE,UAAU,EAAE,IAAI,GAAG,CAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAC3D,QAAQ,EAAE,IAAI,GAAG,EAAgB;IACjC,6EAA6E;IAC7E,MAAM,EAAE,IAAI,GAAG,EAAgB;IAC/B,cAAc,EAAE,IAAI,GAAG,CAAe,CAAC,WAAW,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;CAC7E,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAkB,EAAE,EAAgB;IACtE,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAkB;IACvD,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@aletheia-labs/core",
+  "version": "0.1.0",
+  "description": "Aletheia core — types and runtime for memory as governance in LLM agents.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "llm",
+    "memory",
+    "agents",
+    "ai",
+    "authority",
+    "governance",
+    "receipts",
+    "fail-closed"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "smoke:e2e": "tsc -p examples/tsconfig.json && vitest run --config examples/vitest.config.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}