@mcpherson-ai/observa-local-node 0.1.3

package/sdk/contracts/errors.mjs

@@ -0,0 +1,334 @@
+// THE CLOSED REFUSAL BOUNDARY.
+//
+// A public error object cannot safely be a durable provenance token: callers
+// can capture it, decorate it, and replay it through a later callback.  Every
+// foreign-code boundary therefore emits a *fresh*, code-only refusal instead
+// of passing any previously thrown object through.  Internal validation keeps
+// its specific codes by placing narrow `runUntrusted` calls only around the
+// reflection/callback operation that is actually foreign.
+//
+// The object has no caller-controlled detail channel. Its message and
+// detail fields are code-only and immutable; the object itself is frozen.
+// Native Promise results
+// are observed then refused because this synchronous contract cannot allow a
+// later rejection to leak caller text after its closed result has returned.
+
+// EVERY CODE THIS PACKAGE MAY EMIT, in one closed list.
+//
+// Derived mechanically from the source set — every literal in a code-carrying
+// argument position of `refuse`, `refuseOnRawThrow`, `runUntrusted`,
+// `snapshotRecord`, `exactKeys`, `entryRecord`, `entryArray`,
+// `assertVocabularyValue`, `validateEventPayload` and their siblings, plus the
+// node's entry-code table and the critical section's phase table.
+//
+// FINAL CLOSURE, INDEPENDENT REVIEW #1 — THAT CLAIM USED TO BE FALSE IN ALL
+// THREE PARTS. The list was not derived, nothing re-derived it, and it was
+// wrong in BOTH directions: `PROJECTION_EVENT_PAYLOAD_INVALID` was emitted by
+// the public `projectStateAt` and not declared here, while
+// `EVIDENCE_OUTSIDE_PROFILE_VOCABULARY` was declared and emitted nowhere. The
+// undeclared one escaped because it is bound to a module const and passed by
+// NAME, so even a literal-only scan would have missed it. What stood in for the
+// guard was a test that called six hand-picked methods and asserted their codes
+// were members — it could not see either divergence.
+//
+// `error-provenance.test.mjs` now performs the derivation this comment
+// describes, resolving single-assignment string consts, and fails on a set
+// difference in EITHER direction. A code added to the code without being
+// declared here fails the suite rather than silently becoming
+// `REFUSAL_CODE_UNDECLARED` at runtime.
+export const REFUSAL_CODES = Object.freeze([
+  "ACTION_ALREADY_ATTEMPTED",
+  "ADAPTER_CAPABILITIES_INVALID",
+  "ADAPTER_CAPABILITY_UNSATISFIED",
+  "ADAPTER_CONTRACT_REQUIRED",
+  "ADAPTER_DECLARATION_INVALID",
+  "ADAPTER_ID_INVALID",
+  "ADAPTER_METHOD_NOT_IMPLEMENTED",
+  "ADAPTER_VERSION_INVALID",
+  "AUTHORITY_BINDING_FIELDS_INVALID",
+  "AUTHORITY_BINDING_ID_INVALID",
+  "AUTHORITY_BINDING_NOT_REGISTERED",
+  "AUTHORITY_BINDING_NOT_SUCCESSOR",
+  "AUTHORITY_BINDING_OPTIONS_INVALID",
+  "AUTHORITY_BINDING_SUPERSEDED",
+  "AUTHORITY_BINDING_TAMPERED",
+  "BINDING_ALREADY_SUPERSEDED",
+  "BINDING_OUTSIDE_PROFILE_VOCABULARY",
+  "BINDING_PROFILE_MISMATCH",
+  "BINDING_REVISION_PROFILE_MISMATCH",
+  "BINDING_REVISION_REASON_INVALID",
+  "BINDING_REVISION_REASON_UNEXPECTED",
+  "BINDING_REVISION_TENANT_MISMATCH",
+  "BOUND_INTENT_FIELDS_INVALID",
+  "BOUND_INTENT_ID_INVALID",
+  "BOUND_INTENT_OPTIONS_INVALID",
+  "BOUND_INTENT_TAMPERED",
+  "CAPABILITY_NOT_DECLARED",
+  "CLOCK_INVALID",
+  "CLOCK_REQUIRED",
+  "COMPARISON_INPUT_INVALID",
+  "CORRECTION_AUTHORITY_MISMATCH",
+  "CORRECTION_ERA_MISMATCH",
+  "CORRECTION_REVISION_NOT_DISTINCT",
+  "CORRECTION_RULE_INVALID",
+  "CORRECTION_RULE_NOT_REGISTERED",
+  "CORRECTION_SEMANTICS_MISSING",
+  "CORRECTION_SOURCE_MISMATCH",
+  "CORRECTION_TARGET_REQUIRED",
+  "CROSS_INTENT_SUPERSESSION_REFUSED",
+  "CROSS_TENANT_REFUSED",
+  "ENTRY_POINT_NOT_DECLARED",
+  "ENVELOPE_ACCESSOR_FIELD",
+  "ENVELOPE_BINDING_MISMATCH",
+  "ENVELOPE_CONTEXT_INVALID",
+  "ENVELOPE_DESCRIPTOR_INVALID",
+  "ENVELOPE_INCONSISTENT",
+  "ENVELOPE_INVALID_ENUM",
+  "ENVELOPE_INVALID_FORMAT",
+  "ENVELOPE_INVALID_TYPE",
+  "ENVELOPE_MISSING_FIELD",
+  "ENVELOPE_NESTED_OBJECT",
+  "ENVELOPE_NOT_PLAIN_OBJECT",
+  "ENVELOPE_OUTSIDE_PROFILE_VOCABULARY",
+  "ENVELOPE_PROJECTION_INVALID",
+  "ENVELOPE_SERIALIZED_INPUT",
+  "ENVELOPE_SYMBOL_FIELD",
+  "ENVELOPE_UNKNOWN_FIELD",
+  "EVIDENCE_APPEND_FIELDS_INVALID",
+  "EVIDENCE_APPEND_OPTIONS_INVALID",
+  "EVIDENCE_BEFORE_ACTION",
+  "EVIDENCE_ERA_INVALID",
+  "EVIDENCE_FINGERPRINT_INVALID",
+  "EVIDENCE_IDENTITY_CONFLICT",
+  "EVIDENCE_LOG_GENERATION_INVALID",
+  "EVIDENCE_LOG_OPTIONS_INVALID",
+  "EVIDENCE_LOG_STALE",
+  "EVIDENCE_PAYLOAD_INVALID",
+  "EVIDENCE_PAYLOAD_REQUIRED",
+  "EVIDENCE_READ_EPOCH_INVALID",
+  "EVIDENCE_RECORDED_AT_INVALID",
+  "EVIDENCE_RELATION_INVALID",
+  "EVIDENCE_SOURCE_INVALID",
+  "EVIDENCE_SOURCE_OUTSIDE_PROFILE_VOCABULARY",
+  "EVIDENCE_SOURCE_REQUIRED",
+  "INTENT_ALREADY_REVISED",
+  "INTENT_OUTSIDE_PROFILE_VOCABULARY",
+  "INTENT_PROFILE_MISMATCH",
+  "INTENT_REVISION_PROFILE_MISMATCH",
+  "INTENT_REVISION_REASON_INVALID",
+  "INTENT_REVISION_REASON_UNEXPECTED",
+  "INTENT_REVISION_TENANT_MISMATCH",
+  "INVALID_LOCAL_TENANT",
+  "NODE_APPEND_DURING_EVALUATION",
+  "NODE_CRITICAL_STATE_MOVED",
+  "NODE_METHOD_NOT_IMPLEMENTED",
+  "NODE_QUERY_INVALID",
+  "NODE_REENTRANT_APPEND",
+  "NODE_REENTRANT_OPERATION",
+  "NODE_SHAPE_INVALID",
+  "NODE_SURFACE_EMITS_AUTHORITY",
+  "NON_EVIDENCE_RELATION_REFUSED",
+  "NO_APPLICABLE_EVIDENCE",
+  "PRIOR_EVIDENCE_APPLICABILITY_REQUIRED",
+  "PRIOR_EVIDENCE_APPLICABILITY_UNEXPECTED",
+  "PROFILE_BEHAVIOUR_NOT_INSPECTABLE",
+  "PROFILE_CLASSIFICATION_INVALID",
+  "PROFILE_CONTRACT_VERSION_MISMATCH",
+  "PROFILE_DESCRIPTOR_INVALID",
+  "PROFILE_EVALUATION_FAILED",
+  "PROFILE_NOT_REGISTERED",
+  "PROFILE_OUTCOME_CAUSE_REQUIRED",
+  "PROFILE_OUTCOME_INCONSISTENT",
+  "PROFILE_OUTCOME_INVALID",
+  "PROFILE_OUTCOME_OWNER_REQUIRED",
+  "PROFILE_OUTCOME_OWNER_UNKNOWN",
+  "PROFILE_OUTCOME_REASON_UNKNOWN",
+  "PROFILE_REASON_CODE_COLLISION",
+  "PROFILE_SHAPE_INVALID",
+  "PROFILE_VERSION_REWRITE_ATTEMPT",
+  "PROJECTION_EVENTS_INVALID",
+  "PROJECTION_EVENT_INVALID",
+  "PROJECTION_EVENT_PAYLOAD_INVALID",
+  "PROJECTION_INTENT_MISMATCH",
+  "PROJECTION_RECOVERY_INCOMPLETE",
+  "PROJECTION_SEQUENCE_GAP",
+  "PROJECTION_SEQUENCE_INVALID",
+  "PROJECTION_STATE_INVALID",
+  "READBACK_DEADLINE_NOT_REACHED",
+  "READBACK_NOT_PENDING",
+  "READBACK_POLICY_INVALID",
+  "READBACK_POLICY_REQUIRED",
+  "READBACK_STILL_PENDING",
+  "RECOVERY_CAUSE_REQUIRED",
+  "RECOVERY_CAUSE_UNEXPECTED",
+  "RECOVERY_CAUSE_UNKNOWN",
+  "RECOVERY_IN_PROGRESS",
+  "RECOVERY_NOT_APPLICABLE",
+  "RECOVERY_NOT_OPEN",
+  "RECOVERY_OWNER_UNKNOWN",
+  // ROUND-2 REVIEW #1, H1R2-04. A verdict may not close a repair that no fresh
+  // evidence resolved. Distinct from RECOVERY_IN_PROGRESS, which answers the
+  // narrower "somebody is already working on it".
+  "RECOVERY_UNRESOLVED",
+  // ROUND-2 REVIEW #1, H1R2-01. The fallback for a code this package never
+  // declared: the only way a non-member string can leave this file.
+  "REFUSAL_CODE_UNDECLARED",
+  "RELATION_SUPERSESSION_MISMATCH",
+  "RUNTIME_CLASS_INVALID",
+  "SUPERSESSION_TARGET_ALREADY_SUPERSEDED",
+  "SUPERSESSION_TARGET_NOT_EVIDENCE",
+  "SUPERSESSION_TARGET_UNKNOWN",
+  "TOLERANCE_SPEC_INVALID",
+  "TOLERANCE_SPEC_REQUIRED",
+  "UNKNOWN_BOUND_INTENT",
+  "UNKNOWN_COMPARISON_RULE",
+  "UNKNOWN_EVENT_KIND",
+  "UNKNOWN_EVIDENCE_EVENT",
+  "VALUE_ACCESSOR_REFUSED",
+  "VALUE_ACCESS_REFUSED",
+  "VALUE_CYCLE",
+  "VALUE_NOT_JSON_COMPATIBLE",
+  "VALUE_NOT_PLAIN",
+  "VALUE_TOO_DEEP",
+  "VALUE_TOO_LARGE",
+  "VALUE_UNSAFE_KEY",
+  "VERIFICATION_BEFORE_ACTION",
+  "VOCABULARY_FIELD_UNDECLARED",
+]);
+
+const REGISTRY = new Set(REFUSAL_CODES);
+
+export const UNDECLARED_REFUSAL_CODE = "REFUSAL_CODE_UNDECLARED";
+
+// A REFUSAL CODE IS A MACHINE TOKEN, AND THAT IS THE WHOLE OF WHAT IT MAY BE.
+//
+// The codes above are the ones THIS package emits. They are not the only codes
+// that may exist, because several public helpers — `snapshotRecord`,
+// `exactKeys`, `entryRecord`, `entryArray`, `assertExportSafeText`,
+// `assertVocabularyValue` — take the CALLER'S OWN code so that an external
+// consumer's boundary answers in its own vocabulary. That is a deliberate part
+// of the contract and predates this round.
+//
+// What was never part of the contract is a code that is not a token at all. The
+// the review drove sentences, JSON fragments and caller-authored text
+// through that parameter and read them back out of a public method. The
+// alphabet below is the same positive-allowlist decision
+// `vocabulary-charset.mjs` records for every other machine vocabulary: ASCII
+// UPPER_SNAKE, bounded, anchored. It admits `MY_CODE`; it cannot express a
+// sentence, a path, a JSON blob, a lowercase word or any character outside
+// `[A-Z0-9_]`, so free text cannot survive contact with it.
+//
+// `runUntrusted` below is the control-flow half: a foreign callback cannot use
+// even a well-formed token to choose the enclosing boundary's result.
+const MACHINE_CODE = /^[A-Z][A-Z0-9_]{0,63}$/u;
+
+// Capture the small set of primordials this boundary depends on.  A frozen
+// refusal object is not sufficient when membership or trace construction can
+// be redirected through mutable ambient prototypes after module load.
+const setHas = Function.prototype.call.bind(Set.prototype.has);
+const nativePromiseThen = Function.prototype.call.bind(Promise.prototype.then);
+const regexpTest = Function.prototype.call.bind(RegExp.prototype.test);
+const reflectGet = Reflect.get;
+const defineProperty = Object.defineProperty;
+const freeze = Object.freeze;
+
+export class SdkContractError extends Error {
+  constructor(code) {
+    // NORMALIZED BEFORE `super`, so there is no window in which an undeclared
+    // string is the message. A non-string, a template-built string carrying
+    // caller text, a subclass's chosen code: all become the one fallback.
+    const declared = typeof code === "string" && (setHas(REGISTRY, code) || regexpTest(MACHINE_CODE, code))
+      ? code
+      : UNDECLARED_REFUSAL_CODE;
+    const message = `Observa SDK contract refused (${declared})`;
+    super(message);
+    // NON-WRITABLE AND NON-CONFIGURABLE. A subclass runs its own constructor
+    // body after `super()` returns, and the round-2 review used exactly that to
+    // overwrite `.message` with caller-authored text on an object the
+    // boundary then rethrew. Defining the three fields as immutable own
+    // properties means the shape survives subclassing.
+    defineProperty(this, "name", {
+      value: "SdkContractError", writable: false, configurable: false, enumerable: false,
+    });
+    defineProperty(this, "code", {
+      value: declared, writable: false, configurable: false, enumerable: true,
+    });
+    defineProperty(this, "message", {
+      value: message, writable: false, configurable: false, enumerable: false,
+    });
+    // Engine-generated traces and Error.prepareStackTrace are caller-controlled
+    // detail channels. The contract therefore fixes the detail fields
+    // to code-only values instead of retaining a lazy trace or chained value.
+    defineProperty(this, "stack", {
+      value: message, writable: false, configurable: false, enumerable: false,
+    });
+    defineProperty(this, "cause", {
+      value: undefined, writable: false, configurable: false, enumerable: false,
+    });
+    // No later `defineProperty`, subclass body, or captured-reference replay
+    // may add an attacker-bearing field to an emitted refusal.
+    freeze(this);
+  }
+}
+
+// Raise a code-only refusal.  This public function intentionally carries NO
+// durable "trusted" brand: a caller can capture any public object and replay
+// it later, so object lifetime is not control-flow provenance.
+export function refuse(code) {
+  throw new SdkContractError(code);
+}
+
+// A synchronous H1 boundary cannot safely admit a native Promise: an async
+// profile/clock can reject later with caller text after the synchronous caller
+// has already received a refusal.  Attach a rejection sink first, then refuse
+// synchronously.  The private-slot call does not dispatch through a caller's
+// `.then` property.
+function isNativePromiseAndObserve(value) {
+  if (value === null || (typeof value !== "object" && typeof value !== "function")) return false;
+  try {
+    const observed = nativePromiseThen(value, undefined, () => undefined);
+    nativePromiseThen(observed, undefined, () => undefined);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// A non-native thenable is also outside this synchronous contract.  Reading
+// `then` is fenced here; it is never invoked.  Native Promises were handled
+// above so a rejected one is observed before the closed refusal leaves.
+function hasThenableShape(value) {
+  if (value === null || (typeof value !== "object" && typeof value !== "function")) return false;
+  try {
+    return typeof reflectGet(value, "then") === "function";
+  } catch {
+    return true;
+  }
+}
+
+// Run foreign code and collapse everything it can do to one closed code.
+export function runUntrusted(code, fn, thenableCode = code) {
+  let result;
+  try {
+    result = fn();
+  } catch {
+    refuse(code);
+  }
+  if (isNativePromiseAndObserve(result) || hasThenableShape(result)) refuse(thenableCode);
+  return result;
+}
+
+// Retained as a compatibility query for callers/tests. No public error
+// object is ever a trusted control-flow token; public callers must receive a
+// freshly closed boundary code instead.
+export function isContractRaised(value) {
+  void value;
+  return false;
+}
+
+// Compatibility wrapper for a public callback boundary.  It intentionally
+// recodes *every* thrown value, including a previously emitted SDK error:
+// public object identity cannot prove trustworthy control-flow provenance.
+export function refuseOnRawThrow(code, fn) {
+  return runUntrusted(code, fn);
+}

package/sdk/contracts/stable-primitives.mjs

@@ -0,0 +1,141 @@
+// SMALL PRIMITIVES FOR SECURITY-RELEVANT, ALREADY-VALIDATED DATA.
+//
+// A frozen Array protects its own elements; it does not freeze
+// Array.prototype.  Capability certification and boundary materialization
+// must therefore not dispatch through mutable inherited helpers such as
+// `.includes`, `Symbol.iterator`, spread, or `.push` after validation.
+//
+// These helpers deliberately use indexed access only.  Their callers either
+// hold a contract-owned frozen array or have just materialized a caller array
+// with `entryArray`; they are not general-purpose validators for arbitrary
+// objects.
+
+const NativeArray = Array;
+const freeze = Object.freeze;
+const isSafeInteger = Number.isSafeInteger;
+
+export function stableArrayHas(values, wanted) {
+  const length = values.length;
+  for (let index = 0; index < length; index += 1) {
+    const value = values[index];
+    // SameValueZero is the membership semantics Array#includes supplies,
+    // without dynamically dispatching to a mutable prototype method.
+    if (value === wanted || (value !== value && wanted !== wanted)) return true;
+  }
+  return false;
+}
+
+// Closed grammar checks sometimes use a short string as their vocabulary.
+// Keep those checks off mutable String.prototype for the same reason closed
+// array vocabularies stay off Array.prototype.includes.
+export function stableStringHas(text, wanted) {
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === wanted) return true;
+  }
+  return false;
+}
+
+export function stableArrayCopy(values) {
+  const length = values.length;
+  const copy = new NativeArray(length);
+  for (let index = 0; index < length; index += 1) copy[index] = values[index];
+  return freeze(copy);
+}
+
+// SELECT AND PROJECT WITHOUT DISPATCHING THROUGH `Array.prototype` — FINAL
+// CLOSURE, INDEPENDENT REVIEW #1.
+//
+// `Array.prototype.filter` is ambient mutable behaviour, and this package's own
+// threat model has semi-trusted domain profiles executing in-process (the same
+// class already closed for `GOVERNANCE_WORDS` and for `ID_PATTERNS`, H1R2-06).
+// `EvidenceLog.applicableEvidence()` was `Object.freeze(this.#records.filter(…))`
+// — it FROZE A VALUE IT DID NOT OWN, on the assumption that `filter` returns a
+// fresh array. One assignment inside a profile callback (`Array.prototype.filter
+// = function () { return this; }`) made it return the receiver, so
+// `Object.freeze` froze the log's private `#records`.
+//
+// The result was the worst outcome this contract names: a raw uncoded
+// `TypeError` out of public node methods AND an append-only log destroyed
+// beyond remediation — restoring the prototype does not help, because
+// `#records` stays frozen. Verified: `recordSourceUnavailable` still threw a raw
+// TypeError after `Array.prototype.filter` had been fully restored.
+//
+// The same mutable dispatch sat on the evidence-admissibility decision path and
+// the false-VERIFIED gate in the node. These two helpers are the stable
+// replacements: indexed access only, and the array they freeze is one they
+// constructed themselves.
+export function stableFilter(values, predicate) {
+  const length = values.length;
+  const out = new NativeArray();
+  let count = 0;
+  for (let index = 0; index < length; index += 1) {
+    const value = values[index];
+    if (predicate(value, index)) {
+      out[count] = value;
+      count += 1;
+    }
+  }
+  out.length = count;
+  return out;
+}
+
+export function stableMap(values, project) {
+  const length = values.length;
+  const out = new NativeArray(length);
+  for (let index = 0; index < length; index += 1) out[index] = project(values[index], index);
+  return out;
+}
+
+// Sort a verified, string-valued snapshot without dispatching through the
+// mutable Array prototype.  The small insertion sort is intentional: these
+// callers compare declaration keys, not bulk user data, and the important
+// property is that the ordering mechanism cannot be replaced after import.
+export function stableSortedStringCopy(values) {
+  const copy = new NativeArray(values.length);
+  for (let index = 0; index < values.length; index += 1) copy[index] = values[index];
+  for (let index = 1; index < copy.length; index += 1) {
+    const value = copy[index];
+    let cursor = index - 1;
+    while (cursor >= 0 && copy[cursor] > value) {
+      copy[cursor + 1] = copy[cursor];
+      cursor -= 1;
+    }
+    copy[cursor + 1] = value;
+  }
+  return freeze(copy);
+}
+
+// Integer millisecond timestamps are a bounded numeric domain, not every
+// Number.isInteger value.  JavaScript accepts integers that cannot represent
+// adjacent milliseconds; allowing them into durable history makes ordinary
+// deadline arithmetic non-deterministic at the precision boundary.
+export function isNonNegativeSafeInteger(value) {
+  return isSafeInteger(value) && value >= 0;
+}
+
+export function isPositiveSafeInteger(value) {
+  return isSafeInteger(value) && value > 0;
+}
+
+export function assertNonNegativeSafeInteger(value, code, refuse) {
+  if (!isNonNegativeSafeInteger(value)) refuse(code);
+  return value;
+}
+
+export function assertPositiveSafeInteger(value, code, refuse) {
+  if (!isPositiveSafeInteger(value)) refuse(code);
+  return value;
+}
+
+// Checked arithmetic for the millisecond-number API.  The equality check is
+// intentional: it detects IEEE-754 rounding even in a case where the rounded
+// result happens to remain numerically greater than the start.
+export function addSafeMilliseconds(start, windowMs, code, refuse) {
+  assertNonNegativeSafeInteger(start, code, refuse);
+  assertPositiveSafeInteger(windowMs, code, refuse);
+  const deadline = start + windowMs;
+  if (!isSafeInteger(deadline) || deadline <= start || deadline - start !== windowMs) {
+    refuse(code);
+  }
+  return deadline;
+}