sentinelayer-cli 0.46.5 → 0.48.0

package/src/engram/contracts/temporal-segment.js

@@ -0,0 +1,72 @@
+/**
+ * ENGRAM §EW02 — TemporalSegment contract.
+ *
+ * A TemporalSegment anchors a set of assertions to a specific time window.
+ * It is used for freshness tracking, replay, and time-bounded evidence
+ * retrieval. Every temporal segment must declare its boundaries and a
+ * source snapshot.
+ */
+
+import { z } from "zod";
+import { sourceSnapshotSchema } from "./source-snapshot.js";
+
+export const TEMPORAL_SEGMENT_KINDS = Object.freeze([
+  "session",
+  "observation_window",
+  "ingest_batch",
+  "replay_range",
+]);
+
+export const temporalSegmentKindSchema = z.enum([
+  "session",
+  "observation_window",
+  "ingest_batch",
+  "replay_range",
+]);
+
+/**
+ * A time-bounded segment of the ENGRAM graph.
+ */
+export const temporalSegmentSchema = z.object({
+  segmentId: z.string().min(1),
+  kind: temporalSegmentKindSchema,
+  startTime: z.string().datetime(),
+  endTime: z.string().datetime(),
+  sourceSnapshot: sourceSnapshotSchema,
+  assertionCount: z.number().int().nonnegative().optional(),
+  coverageRatio: z.number().min(0).max(1).optional(),
+  tenantScope: z.string().min(1),
+}).strict().refine(
+  (data) => data.tenantScope === data.sourceSnapshot.tenantScope,
+  { message: "segment tenantScope must match sourceSnapshot tenantScope", path: ["tenantScope"] },
+).refine(
+  (data) => {
+    // Parse timestamps as instants rather than comparing strings.
+    // Lexical comparison can accept ".10Z" > ".1Z" even though they
+    // represent the same instant (luna-judge P2 finding).
+    const startMs = Date.parse(data.startTime);
+    const endMs = Date.parse(data.endTime);
+    if (isNaN(startMs) || isNaN(endMs)) return false;
+    return endMs > startMs;
+  },
+  { message: "endTime must be strictly after startTime (compared as instants)", path: ["endTime"] },
+);
+
+/**
+ * Valid fixture: a complete, valid temporal segment.
+ */
+export const VALID_TEMPORAL_SEGMENT = Object.freeze({
+  segmentId: "ts-session-20261023-001",
+  kind: "session",
+  startTime: "2026-10-23T12:00:00Z",
+  endTime: "2026-10-23T12:30:00Z",
+  sourceSnapshot: {
+    sourceId: "src-session-abc123",
+    sourceType: "session",
+    version: "1.2.0",
+    capturedAt: "2026-10-23T12:00:00Z",
+    tenantScope: "tenant/acme",
+  },
+  assertionCount: 150,
+  tenantScope: "tenant/acme",
+});

package/src/engram/contracts/versions.js

@@ -0,0 +1,96 @@
+/**
+ * ENGRAM §EW02 — Contract version constants and compatibility fixtures.
+ *
+ * Every contract schema carries a canonical version. Consumers use these
+ * constants to declare which contract version they were built against, and
+ * compatibility fixtures verify that old data surfaces parse against the
+ * current schemas.
+ */
+
+/**
+ * Canonical schema versions for EW02 contracts.
+ * Bump these when a contract changes in a way that existing fixtures would
+ * no longer validate.
+ */
+export const CONTRACT_VERSIONS = Object.freeze({
+  graph: "1.0.0",
+  capability: "1.0.0",
+  evidence: "1.0.0",
+  money: "1.0.0",
+  sourceSnapshot: "1.0.0",
+  mediaAsset: "1.0.0",
+  temporalSegment: "1.0.0",
+  taskContextPack: "1.0.0",
+  actionReceipt: "1.0.0",
+});
+
+/**
+ * The supported graph schema version string.
+ */
+export const GRAPH_SCHEMA_VERSION = "1.0.0";
+
+/**
+ * The supported evidence schema version string.
+ */
+export const EVIDENCE_SCHEMA_VERSION = "1.0.0";
+
+/**
+ * Backward-compatibility fixture: a graph from a previous version that must
+ * still validate against the current schema (or be explicitly rejected with a
+ * clear migration path).
+ */
+export const COMPAT_FIXTURES = Object.freeze({
+  /**
+   * Prior-version fixture: a graph from a previous contract version (v0.9.0).
+   * This must either validate against the current schema (migration path) or
+   * be explicitly rejected. It proves that the contract handles version skew,
+   * not just same-version data (luna-judge P2 finding — backward-compat req).
+   */
+  graphV0_9: Object.freeze({
+    // v0.9.0 graph lacking mandatory source field (added in v1.0.0).
+    // The current schema must reject this — silent acceptance of old data
+    // without migration is not allowed.
+    version: "0.9.0",
+    assertions: [
+      {
+        id: "assert-v0_9-001",
+        subject: "entity/a",
+        predicate: "connected_to",
+        object: { target: "entity/b" },
+        provenance: "observed",
+        schemaValidity: "valid",
+      },
+    ],
+    generatedAt: "2026-10-22T00:00:00Z",
+    entities: [
+      {
+        id: "entity/a",
+        type: "node",
+        tenantScope: "tenant/default",
+        sourceVersion: "0.9.0",
+      },
+    ],
+  }),
+
+  /** Graph v1.0.0 current-version minimal valid fixture. */
+  graphV1: Object.freeze({
+    version: "1.0.0",
+    assertions: [
+      {
+        id: "assert-v1-001",
+        subject: "entity/a",
+        predicate: "connected_to",
+        object: { target: "entity/b" },
+        provenance: "observed",
+        schemaValidity: "valid",
+        source: {
+          sourceId: "src-compat-v1",
+          version: "1.0.0",
+          capturedAt: "2026-10-23T00:00:00Z",
+          tenantScope: "tenant/default",
+        },
+      },
+    ],
+    generatedAt: "2026-10-23T00:00:00Z",
+  }),
+});