@remnic/core 9.66.1 → 9.66.3

package/src/shared-context/envelope-actor.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseEnvelopeActor } from "./envelope-actor.js";
+
+test("ok actor returns trimmed actor", () => {
+  assert.deepEqual(parseEnvelopeActor("agent-a"), { ok: true, actor: "agent-a" });
+});
+
+test("empty actor is missing_actor", () => {
+  assert.deepEqual(parseEnvelopeActor(""), { ok: false, error: "missing_actor" });
+  assert.deepEqual(parseEnvelopeActor("   "), { ok: false, error: "missing_actor" });
+});
+
+test("newline in actor is invalid_actor", () => {
+  assert.deepEqual(parseEnvelopeActor("agent-a\nagent-b"), { ok: false, error: "invalid_actor" });
+});
+
+test("trims surrounding whitespace", () => {
+  assert.deepEqual(parseEnvelopeActor("  agent-a  "), { ok: true, actor: "agent-a" });
+});

package/src/shared-context/envelope-actor.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared-item envelope actor parse (issue #1957 leftover).
+ *
+ * Pure. Empty is missing_actor. Newline is invalid_actor.
+ */
+
+export type ParseEnvelopeActorResult =
+  | { ok: true; actor: string }
+  | { ok: false; error: "missing_actor" | "invalid_actor" };
+
+export function parseEnvelopeActor(value: string): ParseEnvelopeActorResult {
+  const actor = value.trim();
+  if (actor.length === 0) return { ok: false, error: "missing_actor" };
+  if (actor.includes("\n")) return { ok: false, error: "invalid_actor" };
+  return { ok: true, actor };
+}

package/src/shared-context/envelope-at.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseEnvelopeAt } from "./envelope-at.js";
+
+const AT = "2026-08-18T12:00:00.000Z";
+
+test("ok at returns ISO string", () => {
+  assert.deepEqual(parseEnvelopeAt(AT), { ok: true, at: AT });
+});
+
+test("empty at is missing_at", () => {
+  assert.deepEqual(parseEnvelopeAt(""), { ok: false, error: "missing_at" });
+  assert.deepEqual(parseEnvelopeAt("   "), { ok: false, error: "missing_at" });
+});
+
+test("invalid at is invalid_at", () => {
+  assert.deepEqual(parseEnvelopeAt("not-a-date"), { ok: false, error: "invalid_at" });
+});

package/src/shared-context/envelope-at.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared-item envelope at parse (issue #1957 leftover).
+ *
+ * Pure. Empty is missing_at. Invalid Date.parse is invalid_at.
+ */
+
+export type ParseEnvelopeAtResult =
+  | { ok: true; at: string }
+  | { ok: false; error: "missing_at" | "invalid_at" };
+
+export function parseEnvelopeAt(value: string): ParseEnvelopeAtResult {
+  const raw = value.trim();
+  if (raw.length === 0) return { ok: false, error: "missing_at" };
+  const ms = Date.parse(raw);
+  if (!Number.isFinite(ms)) return { ok: false, error: "invalid_at" };
+  return { ok: true, at: new Date(ms).toISOString() };
+}

package/src/shared-context/envelope-id.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseEnvelopeId } from "./envelope-id.js";
+
+test("ok id returns trimmed id", () => {
+  assert.deepEqual(parseEnvelopeId("item-a"), { ok: true, id: "item-a" });
+});
+
+test("empty id is missing_id", () => {
+  assert.deepEqual(parseEnvelopeId(""), { ok: false, error: "missing_id" });
+  assert.deepEqual(parseEnvelopeId("   "), { ok: false, error: "missing_id" });
+});
+
+test("newline in id is invalid_id", () => {
+  assert.deepEqual(parseEnvelopeId("item-a\nitem-b"), { ok: false, error: "invalid_id" });
+});
+
+test("trims surrounding whitespace", () => {
+  assert.deepEqual(parseEnvelopeId("  item-a  "), { ok: true, id: "item-a" });
+});

package/src/shared-context/envelope-id.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared-item envelope id parse (issue #1957 leftover).
+ *
+ * Pure. Empty is missing_id. Newline is invalid_id.
+ */
+
+export type ParseEnvelopeIdResult =
+  | { ok: true; id: string }
+  | { ok: false; error: "missing_id" | "invalid_id" };
+
+export function parseEnvelopeId(value: string): ParseEnvelopeIdResult {
+  const id = value.trim();
+  if (id.length === 0) return { ok: false, error: "missing_id" };
+  if (id.includes("\n")) return { ok: false, error: "invalid_id" };
+  return { ok: true, id };
+}

package/src/shared-context/envelope-required.test.ts

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseRequiredActor } from "./envelope-required.js";
+
+test("empty required actor is allowed", () => {
+  assert.deepEqual(parseRequiredActor(""), { ok: true, required: "" });
+  assert.deepEqual(parseRequiredActor("   "), { ok: true, required: "" });
+});
+
+test("ok required actor returns trimmed value", () => {
+  assert.deepEqual(parseRequiredActor("agent-a"), { ok: true, required: "agent-a" });
+});
+
+test("newline in required actor is invalid_required", () => {
+  assert.deepEqual(parseRequiredActor("agent-a\nagent-b"), {
+    ok: false,
+    error: "invalid_required",
+  });
+});
+
+test("trims surrounding whitespace", () => {
+  assert.deepEqual(parseRequiredActor("  agent-a  "), { ok: true, required: "agent-a" });
+});

package/src/shared-context/envelope-required.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared-item envelope required-actor parse (issue #1957 leftover).
+ *
+ * Pure. Empty is allowed (no requirement). Newline is invalid_required.
+ */
+
+export type ParseRequiredActorResult =
+  | { ok: true; required: string }
+  | { ok: false; error: "invalid_required" };
+
+export function parseRequiredActor(value: string): ParseRequiredActorResult {
+  const required = value.trim();
+  if (required.includes("\n")) return { ok: false, error: "invalid_required" };
+  return { ok: true, required };
+}

package/src/shared-context/envelope-ttl.test.ts

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { remainingTtlMs } from "./envelope-ttl.js";
+
+const EXPIRES_AT = "2026-08-18T12:00:00.000Z";
+const AT = Date.parse(EXPIRES_AT);
+
+test("remainingTtlMs returns null when expiresAt is missing", () => {
+  assert.equal(remainingTtlMs({ nowMs: AT }), null);
+  assert.equal(remainingTtlMs({ expiresAt: undefined, nowMs: AT }), null);
+});
+
+test("remainingTtlMs returns 0 at and after expiry", () => {
+  assert.equal(remainingTtlMs({ expiresAt: EXPIRES_AT, nowMs: AT }), 0);
+  assert.equal(remainingTtlMs({ expiresAt: EXPIRES_AT, nowMs: AT + 1 }), 0);
+  assert.equal(remainingTtlMs({ expiresAt: AT, nowMs: AT }), 0);
+});
+
+test("remainingTtlMs returns expiresAt minus nowMs before expiry", () => {
+  assert.equal(remainingTtlMs({ expiresAt: EXPIRES_AT, nowMs: AT - 1 }), 1);
+  assert.equal(remainingTtlMs({ expiresAt: AT, nowMs: AT - 25 }), 25);
+});
+
+test("remainingTtlMs throws on an invalid expiresAt", () => {
+  assert.throws(() => remainingTtlMs({ expiresAt: "not-a-date", nowMs: AT }), /expiresAt/);
+  assert.throws(() => remainingTtlMs({ expiresAt: "", nowMs: AT }), /expiresAt/);
+  assert.throws(() => remainingTtlMs({ expiresAt: Number.NaN, nowMs: AT }), /expiresAt/);
+});

package/src/shared-context/envelope-ttl.ts

@@ -0,0 +1,35 @@
+/**
+ * Remaining envelope TTL in milliseconds (issue #1957).
+ *
+ * Missing expiresAt means no expiry. Half-open: nowMs >= expiresAt is 0.
+ * Invalid expiresAt throws.
+ */
+
+export interface RemainingTtlMsInput {
+  expiresAt?: string | number;
+  nowMs: number;
+}
+
+export function remainingTtlMs(input: RemainingTtlMsInput): number | null {
+  if (input.expiresAt === undefined) return null;
+  const expiresAtMs = parseExpiresAt(input.expiresAt);
+  if (input.nowMs >= expiresAtMs) return 0;
+  return expiresAtMs - input.nowMs;
+}
+
+function parseExpiresAt(expiresAt: string | number): number {
+  if (typeof expiresAt === "number") {
+    if (!Number.isFinite(expiresAt)) {
+      throw new Error("remainingTtlMs: expiresAt must be a valid timestamp");
+    }
+    return expiresAt;
+  }
+  if (typeof expiresAt !== "string" || expiresAt.trim().length === 0) {
+    throw new Error("remainingTtlMs: expiresAt must be a valid timestamp");
+  }
+  const expiresAtMs = Date.parse(expiresAt);
+  if (!Number.isFinite(expiresAtMs)) {
+    throw new Error("remainingTtlMs: expiresAt must be a valid timestamp");
+  }
+  return expiresAtMs;
+}

package/src/shared-context/provenance.test.ts

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { stampProvenance } from "./provenance.js";
+
+const AT = "2026-08-18T12:00:00.000Z";
+
+test("stampProvenance stamps actor and at onto a new object", () => {
+  const item = { id: "item-1", title: "note" };
+  assert.deepEqual(stampProvenance(item, { actor: "agent-a", at: AT }), {
+    id: "item-1",
+    title: "note",
+    provenance: { actor: "agent-a", at: AT },
+  });
+});
+
+test("stampProvenance does not mutate the input item", () => {
+  const item = { id: "item-1" };
+  const stamped = stampProvenance(item, { actor: "agent-a", at: AT });
+  assert.deepEqual(item, { id: "item-1" });
+  assert.equal("provenance" in item, false);
+  assert.notEqual(stamped, item);
+});
+
+test("stampProvenance rejects an empty actor and an invalid at", () => {
+  const item = { id: "item-1" };
+  const valid = { actor: "agent-a", at: AT };
+  assert.throws(() => stampProvenance(item, { ...valid, actor: "" }), /actor/);
+  assert.throws(() => stampProvenance(item, { ...valid, actor: "   " }), /actor/);
+  assert.throws(() => stampProvenance(item, { ...valid, at: "not-a-date" }), /at/);
+  assert.throws(
+    () => stampProvenance(item, { ...valid, at: Number.NaN as unknown as string }),
+    /at/,
+  );
+});

package/src/shared-context/provenance.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared-item provenance stamp (issue #1957).
+ *
+ * First slice: stamp actor + at onto a new object. Curation wiring
+ * comes later. Does not mutate the input.
+ */
+
+export interface ProvenanceStamp {
+  actor: string;
+  at: string;
+}
+
+export interface StampProvenanceOptions {
+  actor: string;
+  at: string;
+}
+
+// Linear ISO instant. No nested quantifiers.
+const ISO_INSTANT =
+  /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+function isStrictIsoTimestamp(value: string): boolean {
+  const match = ISO_INSTANT.exec(value);
+  if (!match) return false;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const hour = Number(match[4]);
+  const minute = Number(match[5]);
+  const second = Number(match[6]);
+  const utc = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+  return (
+    Number.isFinite(Date.parse(value)) &&
+    utc.getUTCFullYear() === year &&
+    utc.getUTCMonth() === month - 1 &&
+    utc.getUTCDate() === day &&
+    utc.getUTCHours() === hour &&
+    utc.getUTCMinutes() === minute &&
+    utc.getUTCSeconds() === second
+  );
+}
+
+function requireActor(actor: string): string {
+  if (typeof actor !== "string" || actor.trim().length === 0) {
+    throw new Error("stampProvenance: actor must be a non-empty string");
+  }
+  return actor;
+}
+
+function requireAt(at: unknown): string {
+  if (typeof at !== "string" || !isStrictIsoTimestamp(at)) {
+    throw new Error("stampProvenance: at must be a valid ISO-8601 timestamp");
+  }
+  return at;
+}
+
+export function stampProvenance<T extends object>(
+  item: T,
+  stamp: StampProvenanceOptions,
+): T & { provenance: ProvenanceStamp } {
+  return {
+    ...item,
+    provenance: {
+      actor: requireActor(stamp.actor),
+      at: requireAt(stamp.at),
+    },
+  };
+}

package/src/shared-context/staleness.test.ts

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  filterLiveEnvelopes,
+  markSupersededCirculation,
+  type SharedStalenessItem,
+} from "./staleness.js";
+
+test("filterLiveEnvelopes drops at the expiry instant (half-open)", () => {
+  const expiresAt = "2026-08-18T12:00:00.000Z";
+  const at = Date.parse(expiresAt);
+  const live: SharedStalenessItem = { id: "keep", expiresAt };
+  const forever: SharedStalenessItem = { id: "legacy" };
+  const items: SharedStalenessItem[] = [live, forever];
+
+  assert.deepEqual(filterLiveEnvelopes(items, at - 1), items);
+  assert.deepEqual(filterLiveEnvelopes(items, at), [forever]);
+  assert.deepEqual(filterLiveEnvelopes(items, at + 1), [forever]);
+  assert.equal(items.length, 2);
+});
+
+test("markSupersededCirculation flags targets that still circulate", () => {
+  const older: SharedStalenessItem = { id: "item-1", expiresAt: "2026-08-19T00:00:00.000Z" };
+  const newer: SharedStalenessItem = { id: "item-2", supersedes: "item-1" };
+  const other: SharedStalenessItem = { id: "item-3" };
+  const items: SharedStalenessItem[] = [older, newer, other];
+
+
+  const marked = markSupersededCirculation(items);
+  assert.equal(marked[0]?.circulating, true);
+  assert.equal(marked[1]?.circulating, undefined);
+  assert.equal(marked[2]?.circulating, undefined);
+  assert.equal(older.circulating, undefined);
+  assert.notEqual(marked[0], older);
+});

package/src/shared-context/staleness.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared-item staleness (issue #1957).
+ *
+ * Pure helpers. Expired items drop; superseded items that still circulate
+ * get a marker. Callers never `rm`.
+ */
+import { isExpired } from "./governance.js";
+
+export interface SharedStalenessItem {
+  id: string;
+  expiresAt?: string;
+  supersedes?: string;
+  circulating?: boolean;
+}
+
+/** Drop expired items. Half-open: `nowMs >= expiresAt` is expired. */
+export function filterLiveEnvelopes<T extends { expiresAt?: string }>(
+  items: readonly T[],
+  nowMs: number,
+): T[] {
+  return items.filter((item) => !isExpired(item, nowMs));
+}
+
+/**
+ * Mark items whose id appears in another item's `supersedes`.
+ * Returns a new array. Does not mutate input and does not delete files.
+ */
+export function markSupersededCirculation<T extends SharedStalenessItem>(
+  items: readonly T[],
+): T[] {
+  const supersededIds = new Set<string>();
+  for (const item of items) {
+    if (item.supersedes) supersededIds.add(item.supersedes);
+  }
+  return items.map((item) =>
+    supersededIds.has(item.id) ? { ...item, circulating: true } : item,
+  );
+}

package/src/shared-context/trajectories.test.ts

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { publishTrajectory } from "./trajectories.js";
+
+test("publishTrajectory defaults to review and lands pending_review", () => {
+  const result = publishTrajectory({
+    trajectoryId: "traj-1",
+    summary: "ran the check",
+  });
+  assert.deepEqual(result, {
+    ok: true,
+    status: "pending_review",
+    trajectoryId: "traj-1",
+    summary: "ran the check",
+  });
+});
+
+test("publishTrajectory review mode lands pending_review", () => {
+  const result = publishTrajectory({
+    mode: "review",
+    trajectoryId: "traj-1",
+    summary: "ran the check",
+  });
+  assert.equal(result.ok, true);
+  if (result.ok) assert.equal(result.status, "pending_review");
+});
+
+test("publishTrajectory auto mode lands active", () => {
+  const result = publishTrajectory({
+    mode: "auto",
+    trajectoryId: "traj-1",
+    summary: "ran the check",
+  });
+  assert.equal(result.ok, true);
+  if (result.ok) assert.equal(result.status, "active");
+});
+
+test("publishTrajectory off mode returns disabled", () => {
+  assert.deepEqual(
+    publishTrajectory({
+      mode: "off",
+      trajectoryId: "traj-1",
+      summary: "ran the check",
+    }),
+    { ok: false, error: "disabled" },
+  );
+});
+
+test("publishTrajectory rejects an unknown mode", () => {
+  assert.deepEqual(
+    publishTrajectory({
+      mode: "publish",
+      trajectoryId: "traj-1",
+      summary: "ran the check",
+    }),
+    { ok: false, error: "unknown_mode" },
+  );
+});
+
+test("publishTrajectory keeps the summary string and strips tool output", () => {
+  const dirty = {
+    mode: "auto",
+    trajectoryId: "traj-1",
+    summary: "ran the check",
+    toolOutput: "stdout: secret fixture dump",
+  };
+  const result = publishTrajectory(dirty);
+  assert.deepEqual(result, {
+    ok: true,
+    status: "active",
+    trajectoryId: "traj-1",
+    summary: "ran the check",
+  });
+  assert.equal(JSON.stringify(result).includes("stdout"), false);
+  assert.equal("toolOutput" in result, false);
+});

package/src/shared-context/trajectories.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared-context trajectory publish (issue #1957).
+ *
+ * First slice: mode gate + sanitization only. Persistence and
+ * findTrajectories come later.
+ */
+
+export const TRAJECTORY_SHARE_MODES = ["off", "review", "auto"] as const;
+export type TrajectoryShareMode = (typeof TRAJECTORY_SHARE_MODES)[number];
+
+export interface PublishTrajectoryInput {
+  mode?: string;
+  trajectoryId: string;
+  summary: string;
+}
+
+export type PublishTrajectoryResult =
+  | { ok: false; error: "disabled" | "unknown_mode" }
+  | {
+      ok: true;
+      status: "pending_review" | "active";
+      trajectoryId: string;
+      summary: string;
+    };
+
+const MODE_STATUS = {
+  review: "pending_review",
+  auto: "active",
+} as const;
+
+function isTrajectoryShareMode(value: string): value is TrajectoryShareMode {
+  return (TRAJECTORY_SHARE_MODES as readonly string[]).includes(value);
+}
+
+export function publishTrajectory(input: PublishTrajectoryInput): PublishTrajectoryResult {
+  const mode = input.mode ?? "review";
+  if (!isTrajectoryShareMode(mode)) {
+    return { ok: false, error: "unknown_mode" };
+  }
+  if (mode === "off") {
+    return { ok: false, error: "disabled" };
+  }
+  return {
+    ok: true,
+    status: MODE_STATUS[mode],
+    trajectoryId: input.trajectoryId,
+    summary: input.summary,
+  };
+}