@remnic/core 9.65.8 → 9.66.1

package/src/recall-navigate.test.ts

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  expandRecallNode,
+  traverseRecallLink,
+  type RecallNavNode,
+} from "./recall-navigate.js";
+
+function node(extra: Partial<RecallNavNode> = {}): RecallNavNode {
+  return {
+    id: "m1",
+    disclosure: "chunk",
+    ...extra,
+  };
+}
+
+test("expandRecallNode budget 0 is a no-op unavailable", () => {
+  const source = node({
+    payloads: { section: "full section body" },
+  });
+  const result = expandRecallNode(source, { budget: 0 });
+  assert.equal(result.status, "unavailable");
+  if (result.status === "unavailable") {
+    assert.equal(result.reason, "budget_off");
+  }
+  assert.equal("node" in result, false);
+  assert.equal(source.disclosure, "chunk");
+});
+
+test("traverseRecallLink budget 0 is a no-op unavailable", () => {
+  const result = traverseRecallLink(
+    node({
+      links: [{ targetId: "m2", linkType: "supports" }],
+    }),
+    "supports",
+    { budget: 0 },
+  );
+  assert.equal(result.status, "unavailable");
+  if (result.status === "unavailable") {
+    assert.equal(result.reason, "budget_off");
+  }
+  assert.equal("neighbors" in result, false);
+});
+
+test("unknown linkType throws", () => {
+  assert.throws(
+    () => traverseRecallLink(node({ links: [] }), "related", { budget: 10 }),
+    /unknown recall nav linkType/,
+  );
+});
+
+test("traverseRecallLink returns neighbors in deterministic targetId order", () => {
+  const result = traverseRecallLink(
+    node({
+      links: [
+        { targetId: "z-mem", linkType: "contradicts" },
+        { targetId: "a-mem", linkType: "contradicts" },
+        { targetId: "m-mem", linkType: "contradicts" },
+        { targetId: "skip-me", linkType: "supports" },
+      ],
+    }),
+    "contradicts",
+    { budget: 100 },
+  );
+  assert.equal(result.status, "ok");
+  if (result.status !== "ok") return;
+  assert.deepEqual(
+    result.neighbors.map((row) => row.id),
+    ["a-mem", "m-mem", "z-mem"],
+  );
+});
+
+test("no matching links is empty, not unavailable", () => {
+  const result = traverseRecallLink(
+    node({
+      links: [{ targetId: "x", linkType: "supports" }],
+    }),
+    "contradicts",
+    { budget: 10 },
+  );
+  assert.equal(result.status, "empty");
+  assert.equal("neighbors" in result, false);
+});

package/src/recall-navigate.ts

@@ -0,0 +1,100 @@
+/**
+ * Recall navigation helpers (issue #1956 first slice).
+ *
+ * Pure expand/traverse over disclosure levels and typed links. No LLM, no IO.
+ * Surfaces (MCP/HTTP/CLI) and parseConfig wiring wait for a later PR —
+ * config.ts is at its fileSizeGrandfather ceiling.
+ *
+ * Budget 0 is off (unavailable). Empty means the step ran and found nothing.
+ */
+import {
+  RECALL_DISCLOSURE_LEVELS,
+  type RecallDisclosure,
+} from "./types.js";
+
+export const RECALL_NAV_LINK_TYPES = [
+  "supports",
+  "contradicts",
+  "elaborates",
+  "supersedes",
+  "causes",
+] as const;
+
+export type RecallNavLinkType = (typeof RECALL_NAV_LINK_TYPES)[number];
+
+export interface RecallNavBudget {
+  budget: number;
+}
+
+export interface RecallNavEdge {
+  targetId: string;
+  linkType: string;
+  preview?: string;
+}
+
+export interface RecallNavNode {
+  id: string;
+  disclosure: RecallDisclosure;
+  payloads?: Partial<Record<RecallDisclosure, string>>;
+  links?: readonly RecallNavEdge[];
+}
+
+export interface RecallNavNeighbor {
+  id: string;
+  linkType: RecallNavLinkType;
+  preview?: string;
+}
+
+export type RecallNavExpandResult =
+  | { status: "ok"; node: { id: string; disclosure: RecallDisclosure; text: string } }
+  | { status: "empty" }
+  | { status: "unavailable"; reason: "budget_off" };
+
+export type RecallNavTraverseResult =
+  | { status: "ok"; neighbors: readonly RecallNavNeighbor[] }
+  | { status: "empty" }
+  | { status: "unavailable"; reason: "budget_off" };
+
+export function isRecallNavLinkType(value: unknown): value is RecallNavLinkType {
+  return typeof value === "string" && (RECALL_NAV_LINK_TYPES as readonly string[]).includes(value);
+}
+
+export function expandRecallNode(
+  node: RecallNavNode,
+  options: RecallNavBudget,
+): RecallNavExpandResult {
+  if (!Number.isFinite(options.budget) || options.budget <= 0) {
+    return { status: "unavailable", reason: "budget_off" };
+  }
+  const current = RECALL_DISCLOSURE_LEVELS.indexOf(node.disclosure);
+  const next = current >= 0 ? RECALL_DISCLOSURE_LEVELS[current + 1] : undefined;
+  if (next === undefined) return { status: "empty" };
+  const text = node.payloads?.[next];
+  if (typeof text !== "string") return { status: "empty" };
+  return { status: "ok", node: { id: node.id, disclosure: next, text } };
+}
+
+export function traverseRecallLink(
+  from: RecallNavNode,
+  linkType: string,
+  options: RecallNavBudget,
+): RecallNavTraverseResult {
+  if (!isRecallNavLinkType(linkType)) {
+    throw new Error(
+      `unknown recall nav linkType: ${JSON.stringify(linkType)}. Valid: ${RECALL_NAV_LINK_TYPES.join(", ")}`,
+    );
+  }
+  if (!Number.isFinite(options.budget) || options.budget <= 0) {
+    return { status: "unavailable", reason: "budget_off" };
+  }
+  const neighbors = (from.links ?? [])
+    .filter((link) => link.linkType === linkType)
+    .map((link) => {
+      const neighbor: RecallNavNeighbor = { id: link.targetId, linkType };
+      if (link.preview !== undefined) neighbor.preview = link.preview;
+      return neighbor;
+    })
+    .sort((a, b) => a.id.localeCompare(b.id, "en"));
+  if (neighbors.length === 0) return { status: "empty" };
+  return { status: "ok", neighbors };
+}

package/src/recall-state-view-wire.test.ts

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { applyRecallStateViews } from "./recall-state-view-wire.js";
+import type { StateViewResult } from "./recall-state-view.js";
+
+function fact(id: string, extra: Partial<StateViewResult> = {}): StateViewResult {
+  return { id, ...extra };
+}
+
+const PAIR: StateViewResult[] = [
+  fact("new-job", { status: "active" }),
+  fact("old-job", { status: "superseded", supersededBy: "new-job", supersededAt: "2026-03-01" }),
+];
+
+test("recallStateViews false is identity (same array reference)", () => {
+  const input = PAIR.map((row) => ({ ...row }));
+  assert.equal(applyRecallStateViews(input, "when did the job title change", {}), input);
+  assert.equal(
+    applyRecallStateViews(input, "when did the job title change", { recallStateViews: false }),
+    input,
+  );
+  assert.equal(input[0]?.stateLabel, undefined);
+});
+
+test("change-intent query labels a synthetic superseded pair when recallStateViews is on", () => {
+  const labeled = applyRecallStateViews(PAIR, "when did the job title change", {
+    recallStateViews: true,
+  });
+  assert.equal(labeled.length, 2);
+  assert.equal(labeled[0]?.id, "new-job");
+  assert.equal(labeled[0]?.stateLabel, "current");
+  assert.equal(labeled[1]?.id, "old-job");
+  assert.equal(labeled[1]?.stateLabel, "historical");
+});

package/src/recall-state-view-wire.ts

@@ -0,0 +1,28 @@
+/**
+ * Recall inject seam for state views (issue #1952).
+ *
+ * parseConfig cannot grow (fileSizeGrandfather). Operators set
+ * `recallStateViews` on the live PluginConfig extra field. Default false
+ * is identity. Use parseRecallStateViews — do not read a scattered
+ * config flag property here.
+ */
+
+import {
+  annotateStateView,
+  parseRecallStateViews,
+  type StateViewResult,
+} from "./recall-state-view.js";
+
+export function applyRecallStateViews<T extends StateViewResult>(
+  results: T[],
+  query: string,
+  config: unknown,
+): T[] {
+  const raw =
+    typeof config === "object" && config !== null && "recallStateViews" in config
+      ? (config as { recallStateViews?: unknown }).recallStateViews
+      : undefined;
+  return annotateStateView(results, query, [], {
+    enabled: parseRecallStateViews(raw),
+  });
+}

package/src/recall-state-view.test.ts

@@ -0,0 +1,131 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  annotateStateView,
+  formatSupersededPrefix,
+  isChangeOrientedQuery,
+  parseRecallStateViews,
+  shouldWidenSuperseded,
+  type StateViewChain,
+  type StateViewResult,
+} from "./recall-state-view.js";
+
+function fact(id: string, extra: Partial<StateViewResult> = {}): StateViewResult {
+  return { id, ...extra };
+}
+
+const PAIR: StateViewChain[] = [{ predecessorId: "old-job", successorId: "new-job", supersededAt: "2026-03-01" }];
+
+const PAIR_RESULTS: StateViewResult[] = [
+  fact("new-job", { status: "active" }),
+  fact("old-job", { status: "superseded", supersededBy: "new-job", supersededAt: "2026-03-01" }),
+];
+
+test("change-intent query labels both facts in a superseded pair", () => {
+  const labeled = annotateStateView(PAIR_RESULTS, "when did the job title change", PAIR, { enabled: true });
+  assert.equal(labeled.length, 2);
+  assert.equal(labeled[0]?.id, "new-job");
+  assert.equal(labeled[0]?.stateLabel, "current");
+  assert.equal(labeled[1]?.id, "old-job");
+  assert.equal(labeled[1]?.stateLabel, "historical");
+});
+
+test("change-intent conjugations fire the annotator", () => {
+  const phrases = [
+    "when did we switch",
+    "we used to",
+    "before the move",
+    "after the cutover",
+    "they switched vendors",
+    "she switches stacks",
+    "switching away from it",
+    "the title changed",
+    "it changes next week",
+    "they are changing providers",
+  ];
+  for (const query of phrases) {
+    assert.equal(isChangeOrientedQuery(query), true, query);
+    const labeled = annotateStateView(PAIR_RESULTS, query, PAIR, { enabled: true });
+    assert.equal(labeled[0]?.stateLabel, "current", query);
+    assert.equal(labeled[1]?.stateLabel, "historical", query);
+  }
+});
+
+test("non-change query is identical (same array reference, no labels)", () => {
+  const input = PAIR_RESULTS.map((row) => ({ ...row }));
+  const out = annotateStateView(input, "what is the current job title", PAIR, { enabled: true });
+  assert.equal(out, input);
+  assert.equal(out[0]?.stateLabel, undefined);
+  assert.equal(out[1]?.stateLabel, undefined);
+});
+
+test("recallStateViews false is identity (same array reference)", () => {
+  const input = PAIR_RESULTS.map((row) => ({ ...row }));
+  assert.equal(annotateStateView(input, "when did the job title change", PAIR), input);
+  assert.equal(annotateStateView(input, "when did the job title change", PAIR, { enabled: false }), input);
+  assert.equal(input[0]?.stateLabel, undefined);
+});
+
+test("superseded never appears without its successor", () => {
+  const orphan = [fact("old-job", { status: "superseded", supersededBy: "new-job" })];
+  const out = annotateStateView(orphan, "when did this change", PAIR, { enabled: true });
+  assert.deepEqual(out, []);
+  assert.equal(shouldWidenSuperseded("new-job", new Set(["old-job"])), false);
+  assert.equal(shouldWidenSuperseded("new-job", new Set(["old-job", "new-job"])), true);
+  assert.equal(shouldWidenSuperseded(undefined, new Set(["new-job"])), false);
+});
+
+test("annotateStateView is sort-stable", () => {
+  const reversed = [PAIR_RESULTS[1]!, PAIR_RESULTS[0]!];
+  const labeled = annotateStateView(reversed, "when did the title change", PAIR, { enabled: true });
+  assert.deepEqual(
+    labeled.map((row) => row.id),
+    ["old-job", "new-job"],
+  );
+  assert.equal(labeled[0]?.stateLabel, "historical");
+  assert.equal(labeled[1]?.stateLabel, "current");
+});
+
+test("middle hop of a three-node chain is transition", () => {
+  const chains: StateViewChain[] = [
+    { predecessorId: "v1", successorId: "v2" },
+    { predecessorId: "v2", successorId: "v3" },
+  ];
+  const results = [
+    fact("v1", { status: "superseded", supersededBy: "v2" }),
+    fact("v2", { status: "superseded", supersededBy: "v3" }),
+    fact("v3", { status: "active" }),
+  ];
+  const labeled = annotateStateView(results, "what changed", chains, { enabled: true });
+  assert.deepEqual(
+    labeled.map((row) => [row.id, row.stateLabel]),
+    [
+      ["v1", "historical"],
+      ["v2", "transition"],
+      ["v3", "current"],
+    ],
+  );
+});
+
+test("formatSupersededPrefix matches the injected-block contract", () => {
+  assert.equal(formatSupersededPrefix("2026-03-01", "new-job"), "[superseded 2026-03-01 by new-job]");
+});
+
+test("parseRecallStateViews honors 0/false and defaults off", () => {
+  assert.equal(parseRecallStateViews(undefined), false);
+  assert.equal(parseRecallStateViews(false), false);
+  assert.equal(parseRecallStateViews(0), false);
+  assert.equal(parseRecallStateViews("false"), false);
+  assert.equal(parseRecallStateViews("0"), false);
+  assert.equal(parseRecallStateViews(true), true);
+  assert.equal(parseRecallStateViews(1), true);
+  assert.equal(parseRecallStateViews("true"), true);
+});
+
+test("annotateStateView does not mutate input rows", () => {
+  const input = PAIR_RESULTS.map((row) => ({ ...row }));
+  annotateStateView(input, "when did this change", PAIR, { enabled: true });
+  assert.equal(input[0]?.stateLabel, undefined);
+  assert.equal(input[1]?.stateLabel, undefined);
+});

package/src/recall-state-view.ts

@@ -0,0 +1,138 @@
+/**
+ * Recall state views (issue #1952).
+ *
+ * Config key: `recallStateViews` (default false). When false, annotateStateView
+ * is identity: same array reference, no `stateLabel`. config.ts is at its
+ * fileSizeGrandfather ceiling, so parseConfig wiring waits for a later PR.
+ * Call `parseRecallStateViews` at the recall seam when that lands.
+ *
+ * Change-intent morphology lives here (do not grow intent.ts). A superseded
+ * memory is admitted only when its successor is also in the candidate set.
+ */
+import { coerceBooleanLike } from "./connectors/coerce.js";
+
+export type StateLabel = "current" | "historical" | "transition";
+
+export interface StateViewChain {
+  predecessorId: string;
+  successorId: string;
+  supersededAt?: string;
+}
+
+export interface StateViewResult {
+  id?: string;
+  docid?: string;
+  status?: string;
+  supersededBy?: string;
+  supersededAt?: string;
+  stateLabel?: StateLabel;
+}
+
+export const DEFAULT_RECALL_STATE_VIEWS = false;
+
+const CHANGE_WORDS = ["before", "after", "switch", "switches", "switched", "switching", "change", "changes", "changed", "changing"];
+
+export function parseRecallStateViews(raw: unknown): boolean {
+  return coerceBooleanLike(raw, "recallStateViews") === true;
+}
+
+export function isChangeOrientedQuery(query: string): boolean {
+  const lower = query.toLowerCase();
+  if (lower.includes("when did") || lower.includes("used to")) return true;
+  return CHANGE_WORDS.some((word) => {
+    const idx = lower.indexOf(word);
+    if (idx < 0) return false;
+    const before = idx === 0 || !/[a-z0-9]/.test(lower[idx - 1] ?? "");
+    const afterIdx = idx + word.length;
+    const after = afterIdx >= lower.length || !/[a-z0-9]/.test(lower[afterIdx] ?? "");
+    return before && after;
+  });
+}
+
+export function shouldWidenSuperseded(
+  successorId: string | undefined,
+  candidateIds: ReadonlySet<string>,
+): boolean {
+  return typeof successorId === "string" && successorId.length > 0 && candidateIds.has(successorId);
+}
+
+export function formatSupersededPrefix(date: string, successorId: string): string {
+  return `[superseded ${date} by ${successorId}]`;
+}
+
+export function resultStateViewId(result: StateViewResult): string {
+  return result.id ?? result.docid ?? "";
+}
+
+function buildSuccessorMap(results: readonly StateViewResult[], chains: readonly StateViewChain[]): Map<string, string> {
+  const byPred = new Map<string, string>();
+  for (const chain of chains) {
+    if (chain.predecessorId && chain.successorId) {
+      byPred.set(chain.predecessorId, chain.successorId);
+    }
+  }
+  for (const result of results) {
+    const id = resultStateViewId(result);
+    if (id && result.supersededBy) byPred.set(id, result.supersededBy);
+  }
+  return byPred;
+}
+
+function labelFor(
+  id: string,
+  result: StateViewResult,
+  byPred: Map<string, string>,
+  admittedIds: ReadonlySet<string>,
+): StateLabel {
+  const successorId = result.supersededBy ?? byPred.get(id);
+  const isPred = shouldWidenSuperseded(successorId, admittedIds);
+  let isSucc = false;
+  for (const [predId, succId] of byPred) {
+    if (succId === id && admittedIds.has(predId)) {
+      isSucc = true;
+      break;
+    }
+  }
+  if (isPred && isSucc) return "transition";
+  if (isPred) return "historical";
+  if (isSucc) return "current";
+  return result.status === "superseded" ? "historical" : "current";
+}
+
+export function annotateStateView<T extends StateViewResult>(
+  results: T[],
+  query: string,
+  chains: readonly StateViewChain[],
+  options: { enabled?: boolean } = {},
+): T[] {
+  const enabled = options.enabled === true;
+  if (!enabled || !isChangeOrientedQuery(query)) return results;
+
+  const byPred = buildSuccessorMap(results, chains);
+  const candidateIds = new Set<string>();
+  for (const result of results) {
+    const id = resultStateViewId(result);
+    if (id) candidateIds.add(id);
+  }
+
+  const admitted: T[] = [];
+  for (const result of results) {
+    const id = resultStateViewId(result);
+    const successorId = result.supersededBy ?? byPred.get(id);
+    const superseded = result.status === "superseded" || Boolean(result.supersededBy) || byPred.has(id);
+    if (!superseded || shouldWidenSuperseded(successorId, candidateIds)) {
+      admitted.push(result);
+    }
+  }
+
+  const admittedIds = new Set<string>();
+  for (const result of admitted) {
+    const id = resultStateViewId(result);
+    if (id) admittedIds.add(id);
+  }
+
+  return admitted.map((result) => {
+    const id = resultStateViewId(result);
+    return { ...result, stateLabel: labelFor(id, result, byPred, admittedIds) };
+  });
+}

package/src/schemas.ts

@@ -181,7 +181,7 @@ export const ExtractedFactSchema = z.object({
     .optional()
     .nullable()
     .describe(
-      'For category "reasoning_trace" only: a stored solution chain with ordered steps, a final answer, and an optional observed outcome. Require at least two steps.',
+      'For category "reasoning_trace" only: a stored solution chain with ordered steps, a final answer, and an optional observed outcome. Require at least two steps. IMPORTANT: must include a non-empty finalAnswer (or final_answer) — the JSON Schema sent to providers cannot enforce this constraint.',
     ),
   eventTime: z
     .string()
@@ -350,6 +350,22 @@ export const ExtractionResultSchema = z.object({
     ),
 });
 
+/**
+ * Provider-facing extraction contract. Keep this free of transforms/refinements:
+ * JSON Schema generators cannot faithfully represent salvageArray's ZodEffects.
+ * ExtractionResultSchema remains the authoritative tolerant parser after the
+ * provider returns.
+ */
+export const ExtractionProviderOutputSchema = z.object({
+  facts: z.array(ExtractedFactSchema),
+  profileUpdates: z.array(z.string()),
+  entities: z.array(EntityMentionSchema),
+  questions: z.array(ExtractedQuestionSchema),
+  identityReflection: z.string().optional().nullable(),
+  episodeTitle: z.string().optional().nullable(),
+  relationships: z.array(ExtractedRelationshipSchema).optional().nullable(),
+});
+
 export const ConsolidationItemSchema = z.object({
   existingId: z
     .string()

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

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  applyDefaultEnvelope,
+  isExpired,
+  parseSharedEnvelope,
+} from "./governance.js";
+
+test("applyDefaultEnvelope defaults to informational with no expiry", () => {
+  assert.deepEqual(applyDefaultEnvelope(), { authority: "informational" });
+  assert.deepEqual(applyDefaultEnvelope({}), { authority: "informational" });
+  assert.deepEqual(applyDefaultEnvelope({ authority: "advisory", sharedBy: "agent-a" }), {
+    authority: "advisory",
+    sharedBy: "agent-a",
+  });
+});
+
+test("applyDefaultEnvelope rejects binding without an explicit flag", () => {
+  assert.throws(() => applyDefaultEnvelope({ authority: "binding" }), /binding/);
+  assert.deepEqual(applyDefaultEnvelope({ authority: "binding" }, { binding: true }), {
+    authority: "binding",
+  });
+});
+
+test("isExpired treats expiresAt as a half-open upper bound", () => {
+  const expiresAt = "2026-08-18T12:00:00.000Z";
+  const at = Date.parse(expiresAt);
+  const envelope = { authority: "informational" as const, expiresAt };
+  assert.equal(isExpired(envelope, at - 1), false);
+  assert.equal(isExpired(envelope, at), true);
+  assert.equal(isExpired({}, at), false);
+});
+
+test("parseSharedEnvelope treats a missing legacy envelope as informational with no expiry", () => {
+  assert.deepEqual(parseSharedEnvelope(undefined), { authority: "informational" });
+  assert.deepEqual(parseSharedEnvelope(null), { authority: "informational" });
+  assert.deepEqual(parseSharedEnvelope({ title: "legacy output" }), { authority: "informational" });
+  assert.deepEqual(
+    parseSharedEnvelope({
+      sharedBy: "agent-a",
+      authority: "advisory",
+      expiresAt: "2026-08-18T12:00:00.000Z",
+      supersedes: "item-1",
+    }),
+    {
+      sharedBy: "agent-a",
+      authority: "advisory",
+      expiresAt: "2026-08-18T12:00:00.000Z",
+      supersedes: "item-1",
+    },
+  );
+});

package/src/shared-context/governance.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared-item authority envelope (issue #1957).
+ *
+ * First slice: parse + default + expiry only. Write-path wiring and
+ * curation come later. Binding is never inferred.
+ */
+
+export const SHARED_AUTHORITIES = ["informational", "advisory", "binding"] as const;
+export type SharedAuthority = (typeof SHARED_AUTHORITIES)[number];
+
+export interface SharedEnvelope {
+  sharedBy?: string;
+  authority: SharedAuthority;
+  expiresAt?: string;
+  supersedes?: string;
+}
+
+export interface SharedEnvelopeInput {
+  sharedBy?: string;
+  authority?: string;
+  expiresAt?: string;
+  supersedes?: string;
+}
+
+export interface ApplyDefaultEnvelopeOptions {
+  binding?: boolean;
+}
+
+function isSharedAuthority(value: string): value is SharedAuthority {
+  return (SHARED_AUTHORITIES as readonly string[]).includes(value);
+}
+
+function optionalString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function withOptionalFields(
+  authority: SharedAuthority,
+  source: { sharedBy?: unknown; expiresAt?: unknown; supersedes?: unknown },
+): SharedEnvelope {
+  const envelope: SharedEnvelope = { authority };
+  const sharedBy = optionalString(source.sharedBy);
+  const expiresAt = optionalString(source.expiresAt);
+  const supersedes = optionalString(source.supersedes);
+  if (sharedBy) envelope.sharedBy = sharedBy;
+  if (expiresAt) envelope.expiresAt = expiresAt;
+  if (supersedes) envelope.supersedes = supersedes;
+  return envelope;
+}
+
+export function applyDefaultEnvelope(
+  input: SharedEnvelopeInput = {},
+  options: ApplyDefaultEnvelopeOptions = {},
+): SharedEnvelope {
+  const requested = optionalString(input.authority);
+  if (requested !== undefined && !isSharedAuthority(requested)) {
+    throw new Error(
+      `applyDefaultEnvelope: authority must be informational, advisory, or binding; got ${JSON.stringify(requested)}`,
+    );
+  }
+  if (requested === "binding" && options.binding !== true) {
+    throw new Error("applyDefaultEnvelope: authority \"binding\" requires an explicit binding flag");
+  }
+  return withOptionalFields(requested ?? "informational", input);
+}
+
+export function parseSharedEnvelope(raw: unknown): SharedEnvelope {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { authority: "informational" };
+  }
+  const record = raw as Record<string, unknown>;
+  const requested = optionalString(record.authority);
+  const authority = requested !== undefined && isSharedAuthority(requested) ? requested : "informational";
+  return withOptionalFields(authority, record);
+}
+
+export function isExpired(envelope: Pick<SharedEnvelope, "expiresAt">, nowMs: number): boolean {
+  if (!Number.isFinite(nowMs)) return false;
+  const expiresAt = envelope.expiresAt?.trim();
+  if (!expiresAt) return false;
+  const expiresAtMs = Date.parse(expiresAt);
+  if (!Number.isFinite(expiresAtMs)) return false;
+  return expiresAtMs <= nowMs;
+}