@remnic/core 9.69.4 → 9.69.5

package/dist/who-knows.js

@@ -9,25 +9,25 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-FGORNFTZ.js";
-import "./chunk-PBSZQBFM.js";
+} from "./chunk-NM5EOKN7.js";
+import "./chunk-IFHT77WK.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-4ZWCQJNM.js";
 import "./chunk-WVGXCBOC.js";
-import "./chunk-FNNWK7G7.js";
-import "./chunk-EZPBQVGZ.js";
+import "./chunk-ZET6A3OF.js";
+import "./chunk-JJAOVJ3E.js";
+import "./chunk-N37X5RU7.js";
 import "./chunk-NNBZS3DY.js";
 import "./chunk-CYEPCZN5.js";
 import "./chunk-GIC6BASP.js";
 import "./chunk-YQNNHLCG.js";
-import "./chunk-6KTXE6A3.js";
-import "./chunk-N37X5RU7.js";
 import "./chunk-W7IGLX4G.js";
+import "./chunk-6KTXE6A3.js";
 import "./chunk-GUMZC2BO.js";
-import "./chunk-227UFSEQ.js";
+import "./chunk-7RZJWZ46.js";
+import "./chunk-A7Q43EUZ.js";
 import "./chunk-ET356KSB.js";
 import "./chunk-72A4L5JJ.js";
-import "./chunk-A7Q43EUZ.js";
 import "./chunk-S2V7RUCL.js";
 import "./chunk-XXW32OL7.js";
 import "./chunk-S2HLHAZ4.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.69.4",
+  "version": "9.69.5",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3217,7 +3217,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.69.4"
+    "@remnic/coding-graph": "^9.69.5"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/activity/index.ts

@@ -23,6 +23,7 @@ export * from "./memory-gen.js";
 export * from "./privacy.js";
 export * from "./privacy-delete-plan.js";
 export * from "./privacy-status.js";
+export * from "./privacy-gate-resolve.js";
 export * from "./privacy-window.js";
 export * from "./vault-path.js";
 export * from "./vault-publish.js";
@@ -33,3 +34,4 @@ export * from "./vault-wikilink.js";
 export * from "./vault-region.js";
 export * from "./vault-suffix.js";
 export * from "./vault-join.js";
+export * from "./vault-dry-run.js";

package/src/activity/privacy-gate-resolve.test.ts

@@ -0,0 +1,175 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  type ActivityFeatureGate,
+  ACTIVITY_FEATURE_GATES,
+  resolveActivityGates,
+} from "./privacy-gate-resolve.js";
+
+function allTrue(): Record<string, unknown> {
+  return { analysis: true, journal: true, weekly: true, export: true, memoryCreation: true };
+}
+
+function allFalse(gates: Record<string, boolean>): boolean {
+  return ACTIVITY_FEATURE_GATES.every((gate) => gates[gate] === false);
+}
+
+test("master off forces every explicitly-true gate false", () => {
+  const gates = resolveActivityGates({ enabled: false, gates: allTrue() });
+  for (const gate of ACTIVITY_FEATURE_GATES) {
+    assert.equal(gates[gate], false, `gate "${gate}" must be false`);
+  }
+});
+
+test("master absent behaves as off even with all gates true", () => {
+  const gates = resolveActivityGates({ gates: allTrue() });
+  assert.ok(allFalse(gates));
+});
+
+test("master on with no gates yields all false", () => {
+  const gates = resolveActivityGates({ enabled: true });
+  assert.ok(allFalse(gates));
+  const empty = resolveActivityGates({ enabled: true, gates: {} });
+  assert.ok(allFalse(empty));
+});
+
+test("master on with one gate on leaves the other four off", () => {
+  for (const gate of ACTIVITY_FEATURE_GATES) {
+    const gates = resolveActivityGates({ enabled: true, gates: { [gate]: true } });
+    for (const other of ACTIVITY_FEATURE_GATES) {
+      assert.equal(gates[other], other === gate, `gate "${gate}" case: "${other}" wrong`);
+    }
+  }
+});
+
+test("master on accepts boolean and string token values", () => {
+  const on = resolveActivityGates({
+    enabled: true,
+    gates: { analysis: "true", journal: "1", weekly: "yes", export: "on" },
+  });
+  assert.equal(on.analysis, true);
+  assert.equal(on.journal, true);
+  assert.equal(on.weekly, true);
+  assert.equal(on.export, true);
+
+  const off = resolveActivityGates({
+    enabled: "true",
+    gates: { analysis: "false", journal: "0", weekly: "no", export: "off" },
+  });
+  assert.equal(off.analysis, false);
+  assert.equal(off.journal, false);
+  assert.equal(off.weekly, false);
+  assert.equal(off.export, false);
+});
+
+test("unrecognized gate values throw TypeError naming the gate", () => {
+  for (const value of ["maybe", 2, {}, null]) {
+    assert.throws(
+      () => resolveActivityGates({ enabled: true, gates: { weekly: value } }),
+      (err: unknown) =>
+        err instanceof TypeError && String(err).includes('"weekly"'),
+      `value ${JSON.stringify(value)} must throw`,
+    );
+  }
+});
+
+test("unrecognized gate values throw even when master is off", () => {
+  assert.throws(
+    () => resolveActivityGates({ enabled: false, gates: { journal: "maybe" } }),
+    TypeError,
+  );
+});
+
+test("unknown gate key throws and lists the allow-list", () => {
+  assert.throws(
+    () => resolveActivityGates({ enabled: true, gates: { analytics: true } }),
+    (err: unknown) =>
+      err instanceof TypeError &&
+      /unknown activity gate/.test(String(err)) &&
+      ACTIVITY_FEATURE_GATES.every((gate) => String(err).includes(gate)),
+  );
+});
+
+test("result contains exactly the five gate keys", () => {
+  const gates = resolveActivityGates({ enabled: true, gates: allTrue() });
+  assert.deepEqual(Object.keys(gates).sort(), [...ACTIVITY_FEATURE_GATES].sort());
+});
+
+test("result is frozen and resists mutation", () => {
+  const gates = resolveActivityGates({ enabled: true, gates: { analysis: true } });
+  assert.equal(Object.isFrozen(gates), true);
+  assert.equal(Reflect.set(gates, "analysis", false), false);
+  assert.equal(Reflect.set(gates, "journal", true), false);
+  assert.equal(gates.analysis, true);
+  assert.equal(gates.journal, false);
+});
+
+test("input gates object is not mutated", () => {
+  const input = { analysis: "yes" };
+  resolveActivityGates({ enabled: true, gates: input });
+  assert.deepEqual(input, { analysis: "yes" });
+});
+
+// Review: Object.keys enumerates own properties only, so the unknown-key
+// check never saw an inherited "analysis"; reading by bracket would have
+// honored it anyway. Own-property reads close that.
+test("an inherited gate property is ignored, not honored", () => {
+  const proto = { analysis: true } as Record<string, unknown>;
+  const gates: Record<string, unknown> = Object.create(proto);
+  gates.journal = true; // own, allowed, and genuinely set by the caller
+  const resolved = resolveActivityGates({ enabled: true, gates });
+  assert.equal(resolved.analysis, false, "inherited analysis must not enable");
+  assert.equal(resolved.journal, true, "an own gate still works");
+});
+
+test("the exported gate registry resists runtime mutation", () => {
+  const registry = ACTIVITY_FEATURE_GATES as unknown as string[];
+  assert.throws(() => registry.push("injected"), /not extensible|frozen|read only/i);
+  assert.equal(
+    (ACTIVITY_FEATURE_GATES as readonly string[]).includes("injected"),
+    false,
+  );
+  assert.throws(
+    () => resolveActivityGates({ enabled: true, gates: { injected: true } }),
+    /unknown activity gate/,
+  );
+});
+
+// Round 2: an explicit `readonly string[]` widened the union to `string`.
+test("the frozen registry keeps its literal type", () => {
+  const gates: readonly string[] = ACTIVITY_FEATURE_GATES;
+  // Compile-time narrowing is asserted via the resolver's own typing: at
+  // runtime, the frozen array rejects mutation and injection.
+  assert.throws(() => (gates as string[]).push("bogus"), /not extensible|frozen|read only/i);
+});
+
+// Round 2: a present-but-undefined own value is invalid, not absent.
+test("an explicitly undefined gate value throws rather than reading as false", () => {
+  assert.throws(
+    () => resolveActivityGates({ enabled: true, gates: { analysis: undefined } }),
+    /invalid value for activity gate "analysis"/,
+  );
+  // An absent key is still a legitimate default-false.
+  const resolved = resolveActivityGates({ enabled: true, gates: {} });
+  assert.equal(resolved.analysis, false);
+});
+
+// Round 3: a non-enumerable own key must still hit the unknown-key check.
+test("a non-enumerable unknown gate key is rejected", () => {
+  const gates: Record<string, unknown> = {};
+  Object.defineProperty(gates, "sneaky", { value: true, enumerable: false });
+  assert.throws(
+    () => resolveActivityGates({ enabled: true, gates }),
+    /unknown activity gate "sneaky"/,
+  );
+});
+
+// Compile-time: the frozen registry must keep its literal type, so "bogus"
+// is not assignable to ActivityFeatureGate. This assertion fails the build
+// if a future annotation widens the union back to string.
+test("ActivityFeatureGate stays a literal union", () => {
+  // @ts-expect-error "bogus" is not an ActivityFeatureGate
+  const bogus: ActivityFeatureGate = "bogus";
+  assert.equal(bogus, "bogus");
+});

package/src/activity/privacy-gate-resolve.ts

@@ -0,0 +1,84 @@
+/**
+ * Master-override resolution for activity feature gates (issue #2053).
+ *
+ * With `activity.enabled` false, every feature gate reads false regardless of
+ * its own config value. Gate values accept booleans and the same string tokens
+ * as `parsePrivacyEnabled`; anything else throws so a typo can never silently
+ * disable (or enable) a gate. Internal helper — wiring it into parseConfig is
+ * a later slice.
+ */
+
+import { parsePrivacyEnabled } from "./privacy-enabled.js";
+
+// Frozen at runtime AND still literal-typed: `Object.freeze` preserves the
+// `as const` tuple, so ActivityFeatureGate stays a five-member union for
+// TypeScript consumers while a JavaScript consumer cannot push a key into
+// the array and have resolveActivityGates accept it forever. An explicit
+// `readonly string[]` annotation would widen the union back to `string`.
+export const ACTIVITY_FEATURE_GATES = Object.freeze([
+  "analysis",
+  "journal",
+  "weekly",
+  "export",
+  "memoryCreation",
+] as const);
+export type ActivityFeatureGate = (typeof ACTIVITY_FEATURE_GATES)[number];
+
+export type ActivityGateSet = Readonly<Record<ActivityFeatureGate, boolean>>;
+
+
+function parseGateValue(key: string, value: unknown): boolean {
+  const parsed = parsePrivacyEnabled(value);
+  if (!parsed.ok) {
+    throw new TypeError(
+      `invalid value for activity gate "${key}": ${JSON.stringify(value)} is not a boolean or known token`,
+    );
+  }
+  return parsed.enabled;
+}
+
+export function resolveActivityGates(input: {
+  enabled?: unknown;
+  gates?: Readonly<Record<string, unknown>>;
+}): ActivityGateSet {
+  const rawGates = input.gates;
+  if (rawGates !== undefined && (typeof rawGates !== "object" || rawGates === null || Array.isArray(rawGates))) {
+    throw new TypeError("activity gates must be an object");
+  }
+  if (rawGates) {
+    // getOwnPropertyNames, not Object.keys: a non-enumerable own property
+    // would skip the unknown-key check below while still being readable by
+    // the hasOwn path that resolves values.
+    for (const key of Object.getOwnPropertyNames(rawGates)) {
+      if (!(ACTIVITY_FEATURE_GATES as readonly string[]).includes(key)) {
+        throw new TypeError(
+          `unknown activity gate "${key}"; allowed gates: ${ACTIVITY_FEATURE_GATES.join(", ")}`,
+        );
+      }
+    }
+  }
+
+  const master =
+    input.enabled === undefined ? false : parseGateValue("enabled", input.enabled);
+
+  const result = {} as Record<ActivityFeatureGate, boolean>;
+  for (const gate of ACTIVITY_FEATURE_GATES) {
+    // Object.keys above enumerates OWN properties only, so an inherited
+    // "analysis" never reaches the unknown-key check. Reading it here anyway
+    // would let a gate object with an altered prototype enable a gate the
+    // caller never set: read own properties only.
+    // A PRESENT own key whose value is undefined is not the same as an
+    // absent key: composed config objects often carry explicit undefined,
+    // and the API promises to throw for invalid values, so present-but-
+    // undefined goes through parseGateValue (which refuses it) rather than
+    // silently reading as false.
+    const present = rawGates !== undefined && Object.hasOwn(rawGates, gate);
+    result[gate] = present ? parseGateValue(gate, (rawGates as Record<string, unknown>)[gate]) : false;
+  }
+  if (!master) {
+    for (const gate of ACTIVITY_FEATURE_GATES) {
+      result[gate] = false;
+    }
+  }
+  return Object.freeze(result);
+}

package/src/activity/timeline/index.ts

@@ -25,3 +25,4 @@ export * from "./recap-window.js";
 export * from "./analysis-failure.js";
 export * from "./recap-merge-edits.js";
 export * from "./analysis-metadata.js";
+export * from "./recap-fallback.js";

package/src/activity/timeline/recap-fallback.test.ts

@@ -0,0 +1,184 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { selectRecapForDay } from "./recap-fallback.js";
+
+test("ai wins when present, body returned verbatim", () => {
+  const result = selectRecapForDay({
+    ai: { body: "  AI recap  ", kind: "ai" },
+    previous: { body: "stored journal", kind: "previous" },
+    deterministic: { body: "deterministic render", kind: "deterministic" },
+  });
+  assert.deepEqual(result, { ok: true, body: "  AI recap  ", kind: "ai" });
+});
+
+test("provider failure with a stored previous returns the previous body and carries the failure", () => {
+  const result = selectRecapForDay({
+    previous: { body: "stored journal", kind: "previous" },
+    deterministic: { body: "deterministic render", kind: "deterministic" },
+    failure: "provider_unavailable",
+  });
+  assert.deepEqual(result, {
+    ok: true,
+    body: "stored journal",
+    kind: "previous",
+    failure: "provider_unavailable",
+  });
+});
+
+test("failure with no previous falls to deterministic and still carries the failure", () => {
+  const result = selectRecapForDay({
+    deterministic: { body: "deterministic render", kind: "deterministic" },
+    failure: "timeout",
+  });
+  assert.deepEqual(result, {
+    ok: true,
+    body: "deterministic render",
+    kind: "deterministic",
+    failure: "timeout",
+  });
+});
+
+test("blank ai body falls through to previous", () => {
+  const result = selectRecapForDay({
+    ai: { body: "   ", kind: "ai" },
+    previous: { body: "stored journal", kind: "previous" },
+  });
+  assert.deepEqual(result, {
+    ok: true,
+    body: "stored journal",
+    kind: "previous",
+  });
+});
+
+test("blank previous falls through to deterministic", () => {
+  const result = selectRecapForDay({
+    previous: { body: "", kind: "previous" },
+    deterministic: { body: "deterministic render", kind: "deterministic" },
+  });
+  assert.deepEqual(result, {
+    ok: true,
+    body: "deterministic render",
+    kind: "deterministic",
+  });
+});
+
+test("all candidates absent gives no_recap_available without failure key", () => {
+  const result = selectRecapForDay({});
+  assert.deepEqual(result, { ok: false, error: "no_recap_available" });
+  assert.ok(!("failure" in result));
+});
+
+test("all candidates blank with a failure reports the failure", () => {
+  const result = selectRecapForDay({
+    ai: { body: " ", kind: "ai" },
+    deterministic: { body: "", kind: "deterministic" },
+    failure: "malformed_json",
+  });
+  assert.deepEqual(result, {
+    ok: false,
+    error: "no_recap_available",
+    failure: "malformed_json",
+  });
+});
+
+test("a mislabelled candidate throws", () => {
+  assert.throws(
+    () =>
+      selectRecapForDay({
+        previous: { body: "stored journal", kind: "ai" },
+      }),
+    /kind/,
+  );
+});
+
+test("an unknown kind throws and lists the allow-list", () => {
+  assert.throws(
+    () =>
+      selectRecapForDay({
+        // @ts-expect-error deliberately invalid kind
+        ai: { body: "AI recap", kind: "carrier-pigeon" },
+      }),
+    (error: unknown) => {
+      assert.ok(error instanceof TypeError);
+      assert.match(String(error), /kind/);
+      assert.match(String(error), /ai, deterministic, previous/);
+      return true;
+    },
+  );
+});
+
+test("an absent failure omits the key; whitespace is refused, not cleaned", () => {
+  const result = selectRecapForDay({
+    deterministic: { body: "deterministic render", kind: "deterministic" },
+  });
+  assert.deepEqual(result, {
+    ok: true,
+    body: "deterministic render",
+    kind: "deterministic",
+  });
+  // With the typed contract, whitespace is an unknown kind, not a blank to
+  // silently drop: a caller must omit the field, not send a placeholder.
+  assert.throws(
+    () =>
+      selectRecapForDay({
+        deterministic: { body: "deterministic render", kind: "deterministic" },
+        failure: "   ",
+      }),
+    /unknown recap failure kind/,
+  );
+});
+
+test("input is not mutated", () => {
+  const input = {
+    ai: { body: "  AI recap  ", kind: "ai" },
+    previous: { body: "stored journal", kind: "previous" },
+    deterministic: { body: "deterministic render", kind: "deterministic" },
+    failure: "rate_limited",
+  } as const;
+  const snapshot = structuredClone(input);
+  selectRecapForDay(input);
+  assert.deepEqual(input, snapshot);
+});
+
+// Review: an unknown failure kind must be refused, not echoed into telemetry
+// as though it were typed.
+test("an unknown failure kind throws instead of being echoed", () => {
+  assert.throws(
+    () =>
+      selectRecapForDay({
+        deterministic: { body: "cards", kind: "deterministic" },
+        failure: "timeot",
+      }),
+    /unknown recap failure kind/,
+  );
+  for (const kind of ["timeout", "aborted", "provider_unavailable"]) {
+    const result = selectRecapForDay({
+      deterministic: { body: "cards", kind: "deterministic" },
+      failure: kind,
+    });
+    assert.ok(result.ok);
+    assert.equal(result.failure, kind);
+  }
+});
+
+// Review: a malformed lower-priority candidate must not hide behind a valid
+// higher-priority one. The contract throws on a bad kind whatever wins.
+test("a valid ai candidate does not hide a malformed previous candidate", () => {
+  assert.throws(
+    () =>
+      selectRecapForDay({
+        ai: { body: "fresh", kind: "ai" },
+        previous: { body: "old", kind: "ai" } as never,
+      }),
+    /kind must match its slot/,
+  );
+  assert.throws(
+    () =>
+      selectRecapForDay({
+        ai: { body: "fresh", kind: "ai" },
+        deterministic: { body: "x", kind: "weird" } as never,
+      }),
+    /unknown recap source kind/,
+  );
+});

package/src/activity/timeline/recap-fallback.ts

@@ -0,0 +1,106 @@
+/**
+ * Fallback selection for the daily journal recap (issue #2051).
+ *
+ * Picks the journal body in precedence order: AI render, then the last stored
+ * journal, then the deterministic render. A blank body at any level falls
+ * through to the next one, so a provider failure never replaces a stored good
+ * journal with a thinner deterministic render. This function takes no card
+ * list and performs no writes, so discarding deterministic source cards is not
+ * something it can do; storage callers own that decision.
+ *
+ * Pure: no I/O, no clock. Does not mutate its input. Internal helper; wiring
+ * into the recap build path is a later slice.
+ */
+
+import { isAnalysisFailureKind } from "./analysis-failure.js";
+
+export const RECAP_SOURCE_KINDS = ["ai", "deterministic", "previous"] as const;
+export type RecapSourceKind = (typeof RECAP_SOURCE_KINDS)[number];
+
+export interface RecapCandidate {
+  /** Rendered journal body. */
+  body: string;
+  kind: RecapSourceKind;
+}
+
+export type RecapSelection =
+  | { ok: true; body: string; kind: RecapSourceKind; failure?: string }
+  | { ok: false; error: "no_recap_available"; failure?: string };
+
+const SLOT_ORDER: readonly RecapSourceKind[] = [
+  "ai",
+  "previous",
+  "deterministic",
+];
+
+function isRecapSourceKind(value: unknown): value is RecapSourceKind {
+  return (
+    typeof value === "string" &&
+    (RECAP_SOURCE_KINDS as readonly string[]).includes(value)
+  );
+}
+
+/** Select the journal body for one day. Throws TypeError on a bad kind. */
+export function selectRecapForDay(input: {
+  /** Present only when the AI run succeeded and validated. */
+  ai?: RecapCandidate | null;
+  /** Always available when cards exist: the deterministic render. */
+  deterministic?: RecapCandidate | null;
+  /** The last valid stored journal for this day, if any. */
+  previous?: RecapCandidate | null;
+  /**
+   * Typed failure kind from a provider error, when one occurred. Validated
+   * against the analysis-failure allow-list: an arbitrary string here would
+   * flow into telemetry and downstream exhaustive handling as though it were
+   * a known kind, so a misspelled "timeot" is refused instead of echoed.
+   */
+  failure?: string | null;
+}): RecapSelection {
+  let failure: string | undefined;
+  if (input.failure !== undefined && input.failure !== null) {
+    if (!isAnalysisFailureKind(input.failure)) {
+      throw new TypeError(
+        `unknown recap failure kind; expected one of the analysis failure kinds, got a non-allow-listed value`,
+      );
+    }
+    failure = input.failure;
+  }
+
+  // Validate every supplied candidate FIRST. Returning on the first valid
+  // body would let a malformed lower-priority candidate hide behind a valid
+  // higher-priority one, so the kind contract would hold only sometimes.
+  for (const slot of SLOT_ORDER) {
+    const candidate = input[slot];
+    if (candidate == null) continue;
+
+    const kind = candidate.kind;
+    if (!isRecapSourceKind(kind)) {
+      throw new TypeError(
+        `unknown recap source kind: ${String(kind)}; allowed kinds: ${RECAP_SOURCE_KINDS.join(", ")}`,
+      );
+    }
+    if (kind !== slot) {
+      throw new TypeError(
+        `recap candidate passed as "${slot}" has kind "${kind}"; kind must match its slot`,
+      );
+    }
+    if (typeof candidate.body !== "string") {
+      throw new TypeError(
+        `recap candidate body for slot "${slot}" must be a string`,
+      );
+    }
+  }
+
+  for (const slot of SLOT_ORDER) {
+    const candidate = input[slot];
+    if (candidate == null) continue;
+    if (candidate.body.trim() === "") continue;
+    return failure === undefined
+      ? { ok: true, body: candidate.body, kind: candidate.kind }
+      : { ok: true, body: candidate.body, kind: candidate.kind, failure };
+  }
+
+  return failure === undefined
+    ? { ok: false, error: "no_recap_available" }
+    : { ok: false, error: "no_recap_available", failure };
+}