@remnic/core 9.66.2 → 9.66.4

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),
+    },
+  };
+}