@remnic/core 9.69.40 → 9.69.42

package/src/shared-context/write-output-controls.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Regression: governed write-output envelope controls exposed on BOTH
+ * documented surfaces (issue #2920).
+ *
+ * Covers the canonical client-input parse, the Access MCP operation
+ * (`shared_context_write_output` via the real operation registry), and the
+ * access-service adapter against the REAL manager write path:
+ * - authority: finite allow-list, binding gated by config
+ * - expiresAt: strict ISO, strictly future, bounded by the 10-year TTL
+ * - supersedes: validated id shape
+ * - client `principal`/`namespace` overrides are rejected
+ * - no idempotent replay/dedup semantics on this surface (two identical
+ *   calls write two files — nothing silently swallows a re-send)
+ *
+ * All fixtures are synthetic — no real user data.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+
+import "../access-operations.js";
+import { getOperation } from "../access-boundary.js";
+import { EngramAccessInputError, EngramAccessService, type EngramAccessService as Service } from "../access-service.js";
+import type { Orchestrator } from "../orchestrator.js";
+import { SharedContextManager } from "./manager.js";
+import { MAX_WRITE_EXPIRES_AT_TTL_MS } from "./envelope-io.js";
+import { parseSharedWriteOutputControls } from "./write-output-controls.js";
+import { parseConfig } from "../config.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+async function makeService(overrides: Record<string, unknown> = {}) {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-shared-controls-"));
+  const config = parseConfig({ sharedContextEnabled: true, sharedContextDir: dir, memoryDir: dir, ...overrides });
+  const manager = new SharedContextManager(config);
+  await manager.ensureStructure();
+  const service = new EngramAccessService({ config, sharedContext: manager } as unknown as Orchestrator);
+  return { service, manager, dir, config };
+}
+
+test("parse: controls are strings-or-absent; empty or non-string values reject", () => {
+  assert.deepEqual(parseSharedWriteOutputControls({}), {});
+  assert.deepEqual(parseSharedWriteOutputControls(undefined), {});
+  assert.deepEqual(parseSharedWriteOutputControls(null), {});
+  assert.deepEqual(
+    parseSharedWriteOutputControls({ authority: "advisory", expiresAt: "2030-01-01T00:00:00Z", supersedes: "out-1" }),
+    { authority: "advisory", expiresAt: "2030-01-01T00:00:00Z", supersedes: "out-1" },
+  );
+  assert.throws(() => parseSharedWriteOutputControls({ authority: 7 }), /authority must be a string/);
+  assert.throws(() => parseSharedWriteOutputControls({ expiresAt: "" }), /expiresAt must be a non-empty string/);
+  assert.throws(() => parseSharedWriteOutputControls({ supersedes: "  " }), /supersedes must be a non-empty string/);
+});
+
+test("parse: client principal/namespace overrides are rejected", () => {
+  assert.throws(
+    () => parseSharedWriteOutputControls({ principal: "attacker" }),
+    /principal is server-resolved and cannot be supplied by the caller/,
+  );
+  assert.throws(
+    () => parseSharedWriteOutputControls({ namespace: "victim-ns" }),
+    /namespace is server-resolved and cannot be supplied by the caller/,
+  );
+  // Absent keys (and stripped nulls) pass through untouched.
+  assert.deepEqual(parseSharedWriteOutputControls({ sessionKey: "ctx" }), {});
+});
+
+test("operation: forwards the envelope controls with the authenticated principal", async () => {
+  let received: Record<string, unknown> | undefined;
+  const service = {
+    sharedContextWriteOutput: async (request: Record<string, unknown>) => {
+      received = request;
+      return { written: true, path: "written.md" };
+    },
+  } as unknown as Service;
+  const operation = getOperation("shared_context_write_output");
+  assert.ok(operation);
+
+  await operation.run(
+    { agentId: "agent", title: "t", content: "c", authority: "advisory", expiresAt: "2030-01-01T00:00:00Z", supersedes: "out-1" },
+    { service, authenticatedPrincipal: "real-principal" },
+  );
+  assert.equal(received?.authority, "advisory");
+  assert.equal(received?.expiresAt, "2030-01-01T00:00:00Z");
+  assert.equal(received?.supersedes, "out-1");
+  assert.equal(received?.principal, "real-principal");
+});
+
+test("operation: client principal/namespace and malformed controls are input errors", async () => {
+  const service = {
+    sharedContextWriteOutput: async () => ({ written: true, path: "x" }),
+  } as unknown as Service;
+  const operation = getOperation("shared_context_write_output");
+  assert.ok(operation);
+
+  for (const payload of [
+    { agentId: "a", title: "t", content: "c", principal: "spoofed" },
+    { agentId: "a", title: "t", content: "c", namespace: "other" },
+    { agentId: "a", title: "t", content: "c", authority: "" },
+    { agentId: "a", title: "t", content: "c", expiresAt: 42 },
+  ]) {
+    await assert.rejects(
+      () => operation.run(payload, { service, authenticatedPrincipal: "real-principal" }),
+      (error: unknown) => error instanceof EngramAccessInputError,
+      `must reject ${JSON.stringify(payload)}`,
+    );
+  }
+});
+
+test("service: controls stamp the envelope; absent controls stay informational", async (t) => {
+  const { service, dir } = await makeService();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+
+  const expiresAt = new Date(Date.now() + 90 * DAY_MS).toISOString();
+  const result = (await service.sharedContextWriteOutput({
+    agentId: "agent-alpha",
+    title: "Plan",
+    content: "x",
+    authority: "advisory",
+    expiresAt,
+    supersedes: "out-0001",
+  })) as { written: boolean; path: string };
+  const raw = await readFile(result.path, "utf-8");
+  assert.match(raw, /^authority: "advisory"$/m);
+  assert.ok(raw.includes(`expiresAt: ${JSON.stringify(expiresAt)}`));
+  assert.match(raw, /^supersedes: "out-0001"$/m);
+
+  const plain = (await service.sharedContextWriteOutput({ agentId: "agent-alpha", title: "Plain", content: "x" })) as {
+    written: boolean;
+    path: string;
+  };
+  const plainRaw = await readFile(plain.path, "utf-8");
+  assert.match(plainRaw, /^authority: "informational"$/m);
+});
+
+test("service: binding requires the operator opt-in, else is a client input error", async (t) => {
+  const gated = await makeService();
+  t.after(() => rm(gated.dir, { recursive: true, force: true }));
+  await assert.rejects(
+    () =>
+      gated.service.sharedContextWriteOutput({ agentId: "agent-alpha", title: "Directive", content: "x", authority: "binding" }),
+    (error: unknown) => error instanceof EngramAccessInputError && /requires an explicit binding flag/.test(error.message),
+  );
+
+  const open = await makeService({ sharedContextAllowBindingAuthority: true });
+  t.after(() => rm(open.dir, { recursive: true, force: true }));
+  const result = (await open.service.sharedContextWriteOutput({
+    agentId: "agent-alpha",
+    title: "Directive",
+    content: "x",
+    authority: "binding",
+  })) as { path: string };
+  assert.match(await readFile(result.path, "utf-8"), /^authority: "binding"$/m);
+});
+
+test("service: expiresAt must be strictly future and within the 10-year TTL", async (t) => {
+  const { service, dir } = await makeService();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+
+  const cases: Array<{ expiresAt: string; message: string }> = [
+    { expiresAt: new Date(Date.now() - DAY_MS).toISOString(), message: "strictly after the write time" },
+    { expiresAt: new Date(Date.now() + MAX_WRITE_EXPIRES_AT_TTL_MS + DAY_MS).toISOString(), message: "maximum TTL" },
+    { expiresAt: "2030-02-31T00:00:00Z", message: "valid ISO-8601 timestamp" },
+  ];
+  for (const { expiresAt, message } of cases) {
+    await assert.rejects(
+      () => service.sharedContextWriteOutput({ agentId: "agent-alpha", title: "Expiry", content: "x", expiresAt }),
+      (error: unknown) => error instanceof EngramAccessInputError && error.message.includes(message),
+      `must reject expiresAt=${expiresAt}`,
+    );
+  }
+});
+
+test("service: supersedes must be a non-blank single-line id", async (t) => {
+  const { service, dir } = await makeService();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+  await assert.rejects(
+    () => service.sharedContextWriteOutput({ agentId: "agent-alpha", title: "Supersede", content: "x", supersedes: "out-1\nout-2" }),
+    (error: unknown) => error instanceof EngramAccessInputError && /supersedes/.test(error.message),
+  );
+});
+
+test("service: no idempotent replay — an identical re-send writes a second file", async (t) => {
+  const { service, dir } = await makeService();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+  const base = { agentId: "agent-alpha", title: "Same", content: "same bytes" };
+  const first = (await service.sharedContextWriteOutput(base)) as { path: string };
+  const second = (await service.sharedContextWriteOutput(base)) as { path: string };
+  assert.notEqual(first.path, second.path, "this surface has no replay/dedup semantics; a re-send must not be swallowed");
+});

package/src/shared-context/write-output-controls.ts

@@ -0,0 +1,72 @@
+/**
+ * Canonical client-input parse for shared-context write-output envelope
+ * controls (issue #2920).
+ *
+ * One module feeds BOTH documented surfaces — the Access MCP
+ * `shared_context_write_output` operation and the OpenClaw
+ * `shared_context_write_output` tool — so surface policy can never drift.
+ * This layer owns only what is a SURFACE concern: field type/shape and the
+ * rejection of client-supplied identity. Semantic validation (authority
+ * allow-list, the binding gate, strict ISO instants, the future/TTL expiry
+ * policy, id shape) stays in `composeWriteEnvelope`, the single write-side
+ * gate every path already routes through — there is no in-process bypass
+ * with looser rules than the tool surfaces.
+ */
+
+export interface SharedWriteOutputControls {
+  authority?: string;
+  expiresAt?: string;
+  supersedes?: string;
+}
+
+const CONTROL_FIELDS = ["authority", "expiresAt", "supersedes"] as const;
+
+/** Server-resolved fields a caller must never supply (issue #2920). */
+const SERVER_RESOLVED_FIELDS = ["principal", "namespace"] as const;
+
+/**
+ * Parse the optional envelope controls off a raw client request.
+ *
+ * - Absent fields are omitted; a control must be a non-blank string when
+ *   present (an explicit empty string is a client error, not "unspecified").
+ * - A client-supplied `principal` or `namespace` is rejected: identity and
+ *   scoping are resolved by the surface, never accepted from the caller.
+ *
+ * Throws `Error` with a `shared-context write output:` prefix; access
+ * surfaces map that to their input-error class.
+ */
+export function parseSharedWriteOutputControls(raw: unknown): SharedWriteOutputControls {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const record = raw as Record<string, unknown>;
+  for (const field of SERVER_RESOLVED_FIELDS) {
+    if (Object.hasOwn(record, field) && record[field] !== undefined) {
+      throw new Error(
+        `shared-context write output: ${field} is server-resolved and cannot be supplied by the caller`,
+      );
+    }
+  }
+  const controls: SharedWriteOutputControls = {};
+  for (const field of CONTROL_FIELDS) {
+    const value = record[field];
+    if (value === undefined) continue;
+    if (typeof value !== "string") {
+      throw new Error(`shared-context write output: ${field} must be a string`);
+    }
+    if (value.trim().length === 0) {
+      throw new Error(`shared-context write output: ${field} must be a non-empty string`);
+    }
+    controls[field] = value;
+  }
+  return controls;
+}
+
+const WRITE_INPUT_PREFIXES = [
+  "shared-context write origin mismatch",
+  "applyDefaultEnvelope:",
+  "composeWriteEnvelope:",
+  "shared-context write output:",
+] as const;
+
+export function isSharedContextWriteInputError(message: string): boolean {
+  return WRITE_INPUT_PREFIXES.some((prefix) => message.startsWith(prefix));
+}

package/src/source-attribution.test.ts

@@ -9,6 +9,9 @@ import { ContentHashIndex, StorageManager } from "./storage.js";
 import {
   DEFAULT_CITATION_FORMAT,
   attachCitation,
+  citationTemplateIsDetectable,
+  citationTemplatesForMerge,
+  citationTemplatesToRecognize,
   deriveSessionId,
   formatCitation,
   hasCitation,
@@ -17,6 +20,7 @@ import {
   parseCitation,
   stripCitation,
   stripCitationForTemplate,
+  stripRecognizedCitations,
 } from "./source-attribution.js";
 
 test("formatCitation emits the default template with provided fields", () => {
@@ -171,6 +175,7 @@ test("parseConfig disables inline source attribution by default", () => {
     cfg.inlineSourceAttributionFormat,
     "[Source: agent={agent}, session={sessionId}, ts={ts}]",
   );
+  assert.deepEqual(cfg.inlineSourceAttributionFormatHistory, []);
 });
 
 test("parseConfig honors explicit inline source attribution overrides", () => {
@@ -196,6 +201,22 @@ test("parseConfig falls back to default format when override is empty", () => {
   );
 });
 
+test("parseConfig keeps inlineSourceAttributionFormatHistory when format is normalized", () => {
+  const prior = "[src:{agent}/{sessionId}@{date}]";
+  const current = "[via:{agent}]";
+  const cfg = parseConfig({
+    inlineSourceAttributionFormat: "   ",
+    inlineSourceAttributionFormatHistory: [prior, "", 12, "  ", current],
+  });
+  assert.equal(cfg.inlineSourceAttributionFormat, DEFAULT_CITATION_FORMAT);
+  assert.deepEqual(cfg.inlineSourceAttributionFormatHistory, [prior, current]);
+  assert.deepEqual(citationTemplatesForMerge(cfg), [
+    DEFAULT_CITATION_FORMAT,
+    prior,
+    current,
+  ]);
+});
+
 // ── Finding 1 regression: custom citation template dedup detection ────────────
 
 test("hasCitationForTemplate detects default [Source:...] marker regardless of template", () => {
@@ -539,6 +560,24 @@ test("hasCitationForTemplate: '{agent}{sessionId}' all-placeholder template retu
   );
 });
 
+test("citationTemplateIsDetectable rejects all-placeholder templates", () => {
+  assert.equal(citationTemplateIsDetectable("{agent}{sessionId}"), false);
+  assert.equal(citationTemplateIsDetectable(DEFAULT_CITATION_FORMAT), true);
+  assert.equal(citationTemplateIsDetectable("[src:{agent}/{sessionId}@{date}]"), true);
+});
+
+test("citationTemplatesToRecognize drops undetectable shapes and keeps prior history", () => {
+  const prior = "[src:{agent}/{sessionId}@{date}]";
+  const recognized = citationTemplatesToRecognize("{agent}{sessionId}", [prior]);
+  assert.deepEqual(recognized, [DEFAULT_CITATION_FORMAT, prior]);
+  const body = "The cadence is weekly. [src:agent-a/s-old@2026-08-19]";
+  assert.equal(stripRecognizedCitations(body, recognized), "The cadence is weekly.");
+  assert.deepEqual(citationTemplatesForMerge({ inlineSourceAttributionFormat: prior }), [
+    DEFAULT_CITATION_FORMAT,
+    prior,
+  ]);
+});
+
 test("formatCitation: substituted values containing placeholder syntax are not re-interpreted", () => {
   // Regression for PR #401 (low-severity): the previous implementation chained
   // `.replace(/\{agent\}/g, ...)`, `.replace(/\{ts\}/g, ...)` etc. If the agent

package/src/source-attribution.ts

@@ -482,6 +482,78 @@ export function lastCitationMarkerForTemplate(
   return last;
 }
 
+/**
+ * True when a template can be matched and stripped later. All-placeholder
+ * templates such as `{agent}{sessionId}` have no literal anchors.
+ */
+export function citationTemplateIsDetectable(template: string): boolean {
+  if (typeof template !== "string" || template.length === 0) return false;
+  if (template === DEFAULT_CITATION_FORMAT) return true;
+  PLACEHOLDER_REGEX.lastIndex = 0;
+  if (!PLACEHOLDER_REGEX.test(template)) {
+    PLACEHOLDER_REGEX.lastIndex = 0;
+    return true;
+  }
+  PLACEHOLDER_REGEX.lastIndex = 0;
+  return templateMatcher(template) !== null;
+}
+
+/**
+ * Templates the merge path may lift, preserve, or strip: the default
+ * format, the current format when it is detectable, then any prior
+ * configured formats the caller still holds. Undetectable shapes are
+ * dropped so we never hash or attach a marker we cannot re-match.
+ */
+export function citationTemplatesToRecognize(
+  primary: string | undefined,
+  extra: readonly string[] = [],
+): string[] {
+  const out: string[] = [];
+  const add = (template: string | undefined): void => {
+    if (typeof template !== "string" || template.length === 0) return;
+    if (!citationTemplateIsDetectable(template)) return;
+    if (!out.includes(template)) out.push(template);
+  };
+  add(DEFAULT_CITATION_FORMAT);
+  add(primary);
+  for (const template of extra) add(template);
+  return out;
+}
+
+/**
+ * Prior formats the caller still holds, if any. Absent or malformed
+ * history is ignored — fail safe, do not invent templates.
+ */
+export function citationTemplatesForMerge(config: {
+  inlineSourceAttributionFormat?: string;
+  inlineSourceAttributionFormatHistory?: unknown;
+}): string[] {
+  const raw = config.inlineSourceAttributionFormatHistory;
+  const extra = Array.isArray(raw)
+    ? raw.filter((value): value is string => typeof value === "string" && value.length > 0)
+    : [];
+  return citationTemplatesToRecognize(config.inlineSourceAttributionFormat, extra);
+}
+
+export function lastRecognizedCitationMarker(
+  text: string,
+  templates: readonly string[],
+): string | null {
+  for (const template of templates) {
+    const marker = lastCitationMarkerForTemplate(text, template);
+    if (marker) return marker;
+  }
+  return null;
+}
+
+export function stripRecognizedCitations(text: string, templates: readonly string[]): string {
+  let out = text;
+  for (const template of templates) {
+    out = stripCitationForTemplate(out, template);
+  }
+  return out;
+}
+
 /**
  * Attach an inline citation to fact text.
  *

package/src/types.ts

@@ -1608,6 +1608,11 @@ export interface PluginConfig
    * `[Source: agent={agent}, session={sessionId}, ts={ts}]`.
    */
   inlineSourceAttributionFormat: string;
+  /**
+   * Prior citation templates still recognized after a format change.
+   * Empty when the operator has never changed the template.
+   */
+  inlineSourceAttributionFormatHistory: string[];
   consolidationRequireNonZeroExtraction: boolean;
   consolidationMinIntervalMs: number;
   // QMD maintenance (debounced singleflight)

package/src/wearables/pipeline.ts

@@ -15,6 +15,7 @@
  * write for the run has succeeded.
  */
 
+import { fillWearableConversationLocations } from "../location/tagging.js";
 import { cleanConversation } from "./cleanup.js";
 import { describeErrorForOperator, WearablesInputError } from "./errors.js";
 import {
@@ -50,6 +51,7 @@ import {
   saveSyncState,
   updateSourceSyncState,
 } from "./sync-state.js";
+import type { LocationConfig } from "../location/types.js";
 import type {
   WearableConversation,
   WearableSourceConnector,
@@ -122,6 +124,11 @@ export interface WearableSyncDeps {
   listSupportMemories?(): Promise<Array<{ id: string; content: string }>>;
   /** Clock injection for tests. */
   now?: () => Date;
+  /**
+   * Location config for the missing-only conversation location fill
+   * (issue #2925). Absent, or location tagging disabled, changes nothing.
+   */
+  locationConfig?: LocationConfig;
 }
 
 /** Format a Date as YYYY-MM-DD in the given IANA timezone. */
@@ -382,6 +389,18 @@ export async function syncWearableSource(
     summary.redactions += cleaned.redactions;
     summary.correctionsApplied += cleaned.correctionsApplied;
 
+    // Missing-only location fill (issue #2925): run before the body is
+    // composed so a qualifying dominant-overlap place reaches the day
+    // transcript and memory headers exactly like a provider-supplied
+    // location would. Source-provided values are never overwritten, and
+    // the helper no-ops unless both location gates are on.
+    if (deps.locationConfig) {
+      await fillWearableConversationLocations(cleaned.conversations, {
+        memoryDir: deps.memoryDir,
+        config: deps.locationConfig,
+      });
+    }
+
     if (fetched.conversations.length === 0) {
       // No provider data at all. A transient provider hiccup can
       // legitimately produce an empty result, so an existing stored

package/src/wearables/service.ts

@@ -13,6 +13,7 @@ import {
 } from "./corrections.js";
 import { describeErrorForOperator, WearablesInputError } from "./errors.js";
 import { inferMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
+import type { LocationConfig } from "../location/types.js";
 import { isSupportPassportPrivateMemory } from "../support-passport/card-projection.js";
 import {
   bodyIsEscaped,
@@ -143,6 +144,12 @@ export interface WearablesServiceDeps {
    * fails the sync.
    */
   onDaysSynced?: (days: readonly string[]) => void | Promise<void>;
+  /**
+   * Location config for the missing-only conversation location fill
+   * (issue #2925). Absent changes nothing; the fill itself stays gated
+   * on the location tagging flags.
+   */
+  locationConfig?: LocationConfig;
 }
 
 export interface WearableTranscriptSearchResult {
@@ -351,6 +358,7 @@ export class WearablesService {
         options,
         {
           memoryDir: storage.dir,
+          locationConfig: this.deps.locationConfig,
           readDayContentHash: async (source, date) => {
             const raw = await storage.readWearableDayTranscript(source, date);
             if (raw === null) return null;