@ngockhoale/ukit 3.0.8 → 3.0.9

package/src/core/memory/records.js

@@ -25,6 +25,43 @@ export const RECORD_STATUSES = Object.freeze([
   'archived',
 ]);
 
+export const SCHEMA_VERSION_RECORD = 2;
+
+export const RECORD_TRUST_TIERS = Object.freeze([
+  'verified',
+  'legacy-unverified',
+  'candidate',
+  'observation',
+]);
+
+export const RECORD_REASONS = Object.freeze([
+  'manual',
+  'migration',
+  'promotion',
+  'superseded',
+  'expired',
+  'purged',
+  'review',
+  'unknown-status',
+]);
+
+export const EVIDENCE_KINDS = Object.freeze([
+  'file',
+  'command',
+  'ledger',
+  'manual',
+  'import',
+]);
+
+export const MAX_EVIDENCE = 8;
+export const MAX_LOCATOR = 512;
+
+// Record ids: `mem_<12 hex>` (random, createRecord default) or
+// `v1-<40 hex sha1>` (deterministic migration ids — SPEC §5 FR-001).
+const MEM_ID_RE = /^mem_[0-9a-f]{12}$/;
+const V1_ID_RE = /^v1-[0-9a-f]{40}$/;
+const RECORD_ID_RE = /^(mem_[0-9a-f]{12}|v1-[0-9a-f]{40})$/;
+
 function newId() {
   return `mem_${crypto.randomBytes(6).toString('hex')}`;
 }
@@ -37,8 +74,8 @@ export function validateRecord(record) {
   if (!record || typeof record !== 'object' || Array.isArray(record)) {
     return { ok: false, errors: ['record is not an object'] };
   }
-  if (typeof record.id !== 'string' || !/^mem_[0-9a-f]{12}$/.test(record.id)) {
-    errors.push('id must match mem_<12 hex>');
+  if (typeof record.id !== 'string' || !RECORD_ID_RE.test(record.id)) {
+    errors.push('id must match mem_<12 hex> | v1-<40 hex>');
   }
   if (!RECORD_TYPES.includes(record.type)) {
     errors.push(`type must be one of ${RECORD_TYPES.join('|')}`);
@@ -78,6 +115,64 @@ export function validateRecord(record) {
   if (record.meta == null || typeof record.meta !== 'object' || Array.isArray(record.meta)) {
     errors.push('meta must be an object');
   }
+  if (record.schema_version != null
+      && (!Number.isInteger(record.schema_version) || record.schema_version < 1)) {
+    errors.push('schema_version must be a positive integer');
+  }
+  if (record.evidence != null) {
+    if (!Array.isArray(record.evidence) || record.evidence.length > MAX_EVIDENCE) {
+      errors.push(`evidence must be an array of at most ${MAX_EVIDENCE} entries`);
+    } else {
+      for (const entry of record.evidence) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+          errors.push('evidence entry must be an object');
+          continue;
+        }
+        if (!EVIDENCE_KINDS.includes(entry.kind)) {
+          errors.push(`evidence.kind must be one of ${EVIDENCE_KINDS.join('|')}`);
+        }
+        if (typeof entry.locator !== 'string' || entry.locator.length === 0
+            || entry.locator.length > MAX_LOCATOR) {
+          errors.push(`evidence.locator must be a non-empty string <= ${MAX_LOCATOR} chars`);
+        }
+        if (typeof entry.observed_at !== 'number' || !Number.isFinite(entry.observed_at)) {
+          errors.push('evidence.observed_at must be epoch ms');
+        }
+        if (entry.fingerprint != null && typeof entry.fingerprint !== 'string') {
+          errors.push('evidence.fingerprint must be string | null');
+        }
+        if (!RECORD_TRUST_TIERS.includes(entry.trust_tier)) {
+          errors.push(`evidence.trust_tier must be one of ${RECORD_TRUST_TIERS.join('|')}`);
+        }
+      }
+    }
+  }
+  if (record.valid_from != null
+      && (typeof record.valid_from !== 'number' || !Number.isFinite(record.valid_from))) {
+    errors.push('valid_from must be epoch ms | null');
+  }
+  if (record.revision != null
+      && (!Number.isInteger(record.revision) || record.revision < 1)) {
+    errors.push('revision must be an integer >= 1');
+  }
+  if (record.supersedes != null) {
+    if (!Array.isArray(record.supersedes)
+        || record.supersedes.some((s) => typeof s !== 'string' || !RECORD_ID_RE.test(s))) {
+      errors.push('supersedes must be an array of record ids');
+    } else if (typeof record.id === 'string' && record.supersedes.includes(record.id)) {
+      errors.push('supersedes must not contain own id');
+    }
+  }
+  if (record.superseded_by != null
+      && (typeof record.superseded_by !== 'string' || !RECORD_ID_RE.test(record.superseded_by))) {
+    errors.push('superseded_by must be record id | null');
+  }
+  if (record.trust_tier != null && !RECORD_TRUST_TIERS.includes(record.trust_tier)) {
+    errors.push(`trust_tier must be one of ${RECORD_TRUST_TIERS.join('|')}`);
+  }
+  if (record.reason != null && !RECORD_REASONS.includes(record.reason)) {
+    errors.push(`reason must be one of ${RECORD_REASONS.join('|')}`);
+  }
   return { ok: errors.length === 0, errors };
 }
 
@@ -85,6 +180,7 @@ export function validateRecord(record) {
  * createRecord(input) → record — validates + fills defaults. Throws on invalid input.
  */
 export function createRecord({
+  id = null,
   type,
   scope,
   text,
@@ -95,9 +191,16 @@ export function createRecord({
   projectId = null,
   validUntil = null,
   meta = {},
+  evidence = [],
+  validFrom = null,
+  revision = 1,
+  supersedes = [],
+  supersededBy = null,
+  trustTier = 'verified',
+  reason = 'manual',
 } = {}) {
   const record = {
-    id: newId(),
+    id: id != null ? id : newId(),
     type,
     scope,
     text,
@@ -110,6 +213,14 @@ export function createRecord({
     status: 'active',
     project_id: projectId,
     meta,
+    schema_version: SCHEMA_VERSION_RECORD,
+    evidence,
+    valid_from: validFrom,
+    revision,
+    supersedes,
+    superseded_by: supersededBy,
+    trust_tier: trustTier,
+    reason,
   };
   const { ok, errors } = validateRecord(record);
   if (!ok) {
@@ -129,7 +240,26 @@ export function normalizeRecord(raw) {
   if (!type || !text) return null;
 
   const scope = RECORD_SCOPES.includes(raw.scope) ? raw.scope : 'repo';
-  const status = RECORD_STATUSES.includes(raw.status) ? raw.status : 'active';
+
+  // Fail-safe: unknown status or a record-level schema_version newer than this
+  // build must never coerce to 'active' — archive + flag for review instead.
+  const meta = raw.meta && typeof raw.meta === 'object' && !Array.isArray(raw.meta)
+    ? { ...raw.meta } : {};
+  let status = raw.status == null
+    ? 'active'
+    : (RECORD_STATUSES.includes(raw.status) ? raw.status : null);
+  let reason = RECORD_REASONS.includes(raw.reason) ? raw.reason : 'manual';
+  if (status == null) {
+    status = 'archived';
+    reason = 'unknown-status';
+    meta.unknown_status = String(raw.status).slice(0, 64);
+  } else if (typeof raw.schema_version === 'number'
+      && Number.isInteger(raw.schema_version)
+      && raw.schema_version > SCHEMA_VERSION_RECORD) {
+    status = 'archived';
+    reason = 'unknown-status';
+    meta.unknown_status = `schema_version:${raw.schema_version}`.slice(0, 64);
+  }
 
   let confidence = typeof raw.confidence === 'number' && !Number.isNaN(raw.confidence)
     ? raw.confidence : 1.0;
@@ -141,7 +271,7 @@ export function normalizeRecord(raw) {
     ? raw.valid_until : null;
 
   const record = {
-    id: typeof raw.id === 'string' && /^mem_[0-9a-f]{12}$/.test(raw.id) ? raw.id : newId(),
+    id: typeof raw.id === 'string' && RECORD_ID_RE.test(raw.id) ? raw.id : newId(),
     type,
     scope,
     text,
@@ -154,7 +284,15 @@ export function normalizeRecord(raw) {
     valid_until: validUntil,
     status,
     project_id: typeof raw.project_id === 'string' ? raw.project_id : null,
-    meta: raw.meta && typeof raw.meta === 'object' && !Array.isArray(raw.meta) ? raw.meta : {},
+    meta,
+    schema_version: SCHEMA_VERSION_RECORD,
+    evidence: raw.evidence != null ? raw.evidence : [],
+    valid_from: raw.valid_from != null ? raw.valid_from : null,
+    revision: raw.revision != null ? raw.revision : 1,
+    supersedes: raw.supersedes != null ? raw.supersedes : [],
+    superseded_by: raw.superseded_by != null ? raw.superseded_by : null,
+    trust_tier: raw.trust_tier != null ? raw.trust_tier : 'verified',
+    reason,
   };
 
   const { ok } = validateRecord(record);