@hypercarrier/rarebit 0.1.0-alpha.1

package/test/rarebit-cross-consumer-conformance.test.mjs

@@ -0,0 +1,150 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import { selectRarebits } from "../src/rarebit-core.mjs";
+import { processRarebitSummary } from "../src/rarebit-service.mjs";
+import {
+  parseNativeSession,
+  queryRarebits,
+  resolveActiveBranch,
+} from "../src/rarebit-session.mjs";
+
+const corpus = JSON.parse(
+  await readFile(
+    new URL("./fixtures/conformance-corpus.v1.json", import.meta.url),
+    "utf8",
+  ),
+);
+
+const jsonl = (records) => `${records.map(JSON.stringify).join("\n")}\n`;
+const comparable = (occurrence) => ({
+  sourceEntryId: occurrence.sourceEntryId,
+  role: occurrence.role,
+  outcome: occurrence.outcome,
+  text: occurrence.text,
+});
+
+test("human-reviewed Rarebit corpus names strict and adjacent consumer capabilities", () => {
+  assert.equal(corpus.schemaVersion, 1);
+  assert.equal(corpus.selectorVersion, "rarebit-selector-v1");
+  assert.deepEqual(corpus.capabilities.strictRarebit, [
+    "core",
+    "cli",
+    "pi_extension",
+  ]);
+  assert.match(
+    corpus.capabilities.knownNonconformance.timeline,
+    /active branch/,
+  );
+  for (const description of Object.values(
+    corpus.capabilities.notRarebitProjections,
+  ))
+    assert.equal(typeof description, "string");
+});
+
+for (const fixture of corpus.cases) {
+  test(`strict Rarebit conformance: ${fixture.id}`, () => {
+    const parsed = parseNativeSession(jsonl(fixture.records), fixture.id);
+    const branch = resolveActiveBranch(parsed, fixture.id);
+    assert.deepEqual(
+      branch.map((entry) => entry.id),
+      fixture.expected.activeBranchIds,
+    );
+    const selection = selectRarebits(branch);
+    assert.equal(
+      selection.occurrences.every(
+        (occurrence) => !Object.hasOwn(occurrence, "producer"),
+      ),
+      true,
+    );
+    assert.deepEqual(
+      selection.occurrences.map(comparable),
+      fixture.expected.rarebits,
+    );
+    for (const excluded of fixture.expected.excludedEntryIds)
+      assert.equal(
+        selection.occurrences.some(
+          (occurrence) => occurrence.sourceEntryId === excluded,
+        ),
+        false,
+      );
+  });
+}
+
+test("CLI query and Pi imperative shell consume the same active-branch selection", async () => {
+  const fixture = corpus.cases.find(
+    (candidate) => candidate.id === "fork-compaction-and-resume",
+  );
+  const root = await mkdtemp(join(tmpdir(), "rarebit-conformance-"));
+  const path = join(root, "session.jsonl");
+  await writeFile(path, jsonl(fixture.records));
+
+  const queried = await queryRarebits(path);
+  const expectedIds = fixture.expected.rarebits.map(
+    (occurrence) => occurrence.sourceEntryId,
+  );
+  assert.deepEqual(
+    queried.rarebits.map((occurrence) => occurrence.sourceEntryId),
+    expectedIds,
+  );
+  assert.equal(
+    queried.rarebits.every(
+      (occurrence) => !Object.hasOwn(occurrence, "producer"),
+    ),
+    true,
+  );
+
+  const parsed = parseNativeSession(jsonl(fixture.records), fixture.id);
+  const branch = resolveActiveBranch(parsed, fixture.id);
+  const piShell = await processRarebitSummary(undefined, {
+    branch,
+    sessionId: "session-fork",
+  });
+  assert.equal(piShell.record.status, "skipped_ephemeral_session");
+  assert.equal(piShell.record.selection.occurrenceCount, expectedIds.length);
+  assert.equal(
+    piShell.record.selection.latestUserSourceEntryId,
+    queried.rarebits.filter((occurrence) => occurrence.role === "user").at(-1)
+      ?.sourceEntryId ?? null,
+  );
+});
+
+test("strict reader rejects malformed JSONL instead of returning a partial selection", () => {
+  const fixture = corpus.failureCases.find(
+    (candidate) => candidate.id === "malformed-jsonl",
+  );
+  assert.equal(fixture.expected.strictStatus, "unavailable");
+  assert.throws(
+    () => parseNativeSession(`${fixture.lines.join("\n")}\n`, fixture.id),
+    /malformed JSON/,
+  );
+});
+
+test("strict branch resolver rejects missing lineage instead of guessing", () => {
+  const fixture = corpus.failureCases.find(
+    (candidate) => candidate.id === "missing-active-parent",
+  );
+  const parsed = parseNativeSession(jsonl(fixture.records), fixture.id);
+  assert.equal(fixture.expected.strictStatus, "unavailable");
+  assert.throws(
+    () => resolveActiveBranch(parsed, fixture.id),
+    /missing parent Session entry/,
+  );
+});
+
+test("capped and absent inputs are declared unavailable capabilities, never empty success", () => {
+  for (const id of ["scan-capped", "source-unavailable"]) {
+    const fixture = corpus.failureCases.find(
+      (candidate) => candidate.id === id,
+    );
+    assert.deepEqual(Object.keys(fixture.expected).sort(), [
+      "reason",
+      "strictStatus",
+    ]);
+    assert.equal(fixture.expected.strictStatus, "unavailable");
+    assert.match(fixture.expected.reason, /^(scan_capped|source_unavailable)$/);
+  }
+});

package/test/rarebit-independent-contract.test.mjs

@@ -0,0 +1,317 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+  DEFAULT_RAREBIT_SUMMARY_POLICY,
+  evaluateRarebitSummaryEligibility,
+  measureRarebits,
+  selectRarebits,
+} from "../src/rarebit-core.mjs";
+import { registerRarebitLifecycle } from "../src/lifecycle.mjs";
+import {
+  processRarebitSummary,
+  processRarebitTitle,
+} from "../src/rarebit-service.mjs";
+
+const entry = (id, message, parentId = null) => ({
+  type: "message",
+  id,
+  parentId,
+  timestamp: "2026-07-16T00:00:00.000Z",
+  message,
+});
+
+test("default eligibility is exact at ceil(chars/4)=80k and ratio=0.4", () => {
+  const atBoundary = [
+    entry("u", { role: "user", content: "u".repeat(127_999) }),
+    entry("tool", { role: "toolResult", content: "t".repeat(192_001) }),
+  ];
+  const selected = selectRarebits(atBoundary);
+  const measurement = measureRarebits(atBoundary, selected);
+  assert.equal(measurement.estimatedTotalTokens, 80_000);
+  assert.equal(measurement.rarebitRatio, 0.399996875);
+  assert.equal(
+    evaluateRarebitSummaryEligibility(
+      measurement,
+      DEFAULT_RAREBIT_SUMMARY_POLICY,
+    ).eligible,
+    true,
+  );
+
+  const belowLength = [
+    entry("u", { role: "user", content: "u".repeat(127_999) }),
+    entry("tool", { role: "toolResult", content: "t".repeat(191_997) }),
+  ];
+  const below = measureRarebits(belowLength);
+  assert.equal(below.estimatedTotalTokens, 79_999);
+  assert.deepEqual(
+    evaluateRarebitSummaryEligibility(below, DEFAULT_RAREBIT_SUMMARY_POLICY)
+      .reasons,
+    ["total_length_below_minimum", "rarebit_ratio_above_maximum"],
+  );
+});
+
+test("automatic ineligible does not suppress forced synthesis, whose duplicate returns its settled receipt", async () => {
+  const root = await mkdtemp(join(tmpdir(), "rarebit-dedupe-"));
+  const sessionRoot = join(root, "sessions");
+  await mkdir(sessionRoot);
+  const sessionFile = join(sessionRoot, "session.jsonl");
+  await writeFile(sessionFile, "{}\n");
+  const branch = [entry("u", { role: "user", content: "owner" })];
+  const ctx = {
+    sessionManager: {
+      getHeader: () => ({ id: "dedupe" }),
+      getSessionFile: () => sessionFile,
+      getBranch: () => branch,
+    },
+  };
+  let calls = 0;
+  const config = {
+    sessionRoot,
+    rarebitRoot: join(root, "rarebit"),
+    model: { provider: "test", id: "fake" },
+    modelClient: {
+      complete: async () => {
+        calls += 1;
+        return {
+          text: JSON.stringify({
+            summary:
+              "Progress: one | Findings: two | Questions/Requests: None stated | Next step: three",
+            sessionStatus: "finished",
+            statusReason: "all_requests_accomplished",
+          }),
+        };
+      },
+    },
+  };
+  const automatic = await processRarebitSummary(ctx, config);
+  const forced = await processRarebitSummary(ctx, {
+    ...config,
+    forceSynthesis: true,
+  });
+  const repeatedForced = await processRarebitSummary(ctx, {
+    ...config,
+    forceSynthesis: true,
+  });
+  assert.equal(automatic.record.status, "ineligible");
+  assert.equal(automatic.record.synthesisMode, "automatic");
+  assert.equal(forced.record.status, "ok");
+  assert.equal(forced.record.synthesisMode, "forced");
+  assert.notEqual(automatic.record.jobId, forced.record.jobId);
+  assert.equal(repeatedForced.duplicate, true);
+  assert.equal(repeatedForced.record.status, "ok");
+  assert.equal(repeatedForced.record.summary, forced.record.summary);
+  assert.equal(calls, 1);
+});
+
+test("oversized complete evidence auto-trims and still synthesizes with declared coverage", async () => {
+  const root = await mkdtemp(join(tmpdir(), "rarebit-auto-trim-"));
+  const sessionRoot = join(root, "sessions");
+  await mkdir(sessionRoot);
+  const sessionFile = join(sessionRoot, "session.jsonl");
+  await writeFile(sessionFile, "{}\n");
+  const branch = [
+    entry("old", { role: "user", content: `OLD-${"a".repeat(3_000)}` }),
+    entry(
+      "new",
+      { role: "assistant", stopReason: "stop", content: "NEWEST" },
+      "old",
+    ),
+  ];
+  const ctx = {
+    sessionManager: {
+      getHeader: () => ({ id: "auto-trim" }),
+      getSessionFile: () => sessionFile,
+      getBranch: () => branch,
+    },
+  };
+  let receivedPrompt;
+  let receivedCacheSessionId;
+  const result = await processRarebitSummary(ctx, {
+    sessionRoot,
+    rarebitRoot: join(root, "rarebit"),
+    forceSynthesis: true,
+    lifecycleBoundary: "agent_settled",
+    maxPromptChars: 3_200,
+    model: { provider: "test", id: "fake" },
+    modelClient: {
+      complete: async ({ prompt, cacheSessionId }) => {
+        receivedPrompt = prompt;
+        receivedCacheSessionId = cacheSessionId;
+        return {
+          text: JSON.stringify({
+            summary: "Earlier evidence was trimmed; the newest handoff is present.",
+            sessionStatus: "needs_attention",
+            statusReason: "uncertain",
+          }),
+        };
+      },
+    },
+  });
+  assert.equal(result.record.status, "ok");
+  assert.equal(receivedCacheSessionId, "auto-trim");
+  assert.equal(result.record.sessionStatus, "needs_attention");
+  assert.equal(result.record.statusReason, "uncertain");
+  assert.ok(result.record.inputCoverage.omittedMessageCount > 0);
+  assert.ok(receivedPrompt.length <= 3_200);
+  assert.match(receivedPrompt, /messages before are trimmed/);
+  assert.match(receivedPrompt, /NEWEST/);
+  assert.doesNotMatch(receivedPrompt, /OLD-/);
+});
+
+test("fixed prompt overflow does not suppress a retry with a larger input limit", async () => {
+  const root = await mkdtemp(join(tmpdir(), "rarebit-overflow-"));
+  const sessionRoot = join(root, "sessions");
+  await mkdir(sessionRoot);
+  const sessionFile = join(sessionRoot, "session.jsonl");
+  await writeFile(sessionFile, "{}\n");
+  const branch = [entry("u", { role: "user", content: "owner evidence" })];
+  const ctx = {
+    sessionManager: {
+      getHeader: () => ({ id: "overflow" }),
+      getSessionFile: () => sessionFile,
+      getBranch: () => branch,
+    },
+  };
+  let calls = 0;
+  const common = {
+    sessionRoot,
+    rarebitRoot: join(root, "rarebit"),
+    forceSynthesis: true,
+    model: { provider: "test", id: "fake" },
+    modelClient: {
+      complete: async () => {
+        calls += 1;
+        return {
+          text: JSON.stringify({
+            summary:
+              "Progress: retried | Findings: complete | Questions/Requests: None stated | Next step: inspect",
+            sessionStatus: "finished",
+            statusReason: "all_requests_accomplished",
+          }),
+        };
+      },
+    },
+  };
+  const overflow = await processRarebitSummary(ctx, {
+    ...common,
+    maxPromptChars: 1,
+  });
+  const enlarged = await processRarebitSummary(ctx, {
+    ...common,
+    maxPromptChars: 20_000,
+  });
+  const repeated = await processRarebitSummary(ctx, {
+    ...common,
+    maxPromptChars: 20_000,
+  });
+  assert.equal(overflow.record.status, "unavailable_overflow");
+  assert.equal(enlarged.record.status, "ok");
+  assert.notEqual(overflow.record.jobId, enlarged.record.jobId);
+  assert.equal(repeated.duplicate, true);
+  assert.equal(repeated.record.status, "ok");
+  assert.equal(calls, 1);
+});
+
+test("shared title service produces the same prompt and durable proposal/apply receipts", async () => {
+  const root = await mkdtemp(join(tmpdir(), "rarebit-title-service-"));
+  const sessionRoot = join(root, "sessions");
+  await mkdir(sessionRoot);
+  const sessionFile = join(sessionRoot, "session.jsonl");
+  await writeFile(sessionFile, "{}\n");
+  const branch = [
+    entry("u", { role: "user", content: "Investigate queue latency" }),
+  ];
+  const ctx = {
+    sessionManager: {
+      getHeader: () => ({ id: "title-service" }),
+      getSessionFile: () => sessionFile,
+      getBranch: () => branch,
+    },
+  };
+  const prompts = [];
+  const common = {
+    sessionRoot,
+    rarebitRoot: join(root, "rarebit"),
+    sourceEntryId: "u",
+    titleDate: "2026-07-16",
+    model: { provider: "test", id: "fake" },
+    modelClient: {
+      complete: async ({ prompt }) => {
+        prompts.push(prompt);
+        return { text: "Queue latency investigation" };
+      },
+    },
+  };
+  const proposal = await processRarebitTitle(ctx, common);
+  let applied;
+  const application = await processRarebitTitle(ctx, {
+    ...common,
+    applyTitle: ({ title }) => {
+      applied = title;
+      return { status: "applied" };
+    },
+  });
+  assert.equal(proposal.record.status, "proposal");
+  assert.equal(application.record.status, "applied");
+  assert.equal(applied, "20260716-Queue latency investigation");
+  assert.equal(prompts[0], prompts[1]);
+  assert.equal(
+    JSON.stringify(proposal.record).includes("Investigate queue latency"),
+    false,
+  );
+});
+
+test("lifecycle snapshots persisted user and settled full branches but not ESC", () => {
+  const handlers = new Map();
+  const scheduled = [];
+  registerRarebitLifecycle(
+    { on: (event, handler) => handlers.set(event, handler) },
+    (ctx) => scheduled.push(ctx.sessionManager.getBranch()),
+  );
+  const branch = [entry("u", { role: "user", content: "goal" })];
+  const ctx = {
+    sessionManager: {
+      getHeader: () => ({ id: "lifecycle" }),
+      getSessionFile: () => "/tmp/lifecycle.jsonl",
+      getBranch: () => branch,
+    },
+  };
+  handlers.get("session_start")({}, ctx);
+  scheduled.length = 0;
+  handlers.get("input")({ source: "interactive", text: "goal" }, ctx);
+  handlers.get("message_end")(
+    { message: { role: "user", content: "goal" } },
+    ctx,
+  );
+  handlers.get("before_provider_request")({}, ctx);
+  assert.equal(scheduled.length, 1);
+  handlers.get("agent_end")(
+    { messages: [{ role: "assistant", stopReason: "aborted" }] },
+    ctx,
+  );
+  handlers.get("agent_settled")({}, ctx);
+  assert.equal(scheduled.length, 1, "ESC/aborted must not schedule a summary");
+  branch.push({
+    type: "compaction",
+    id: "c",
+    parentId: "u",
+    summary: "derived compacted view",
+  });
+  branch.push(
+    entry("a", { role: "assistant", stopReason: "stop", content: "done" }, "c"),
+  );
+  handlers.get("agent_end")(
+    { messages: [{ role: "assistant", stopReason: "stop" }] },
+    ctx,
+  );
+  handlers.get("agent_settled")({}, ctx);
+  assert.equal(scheduled.length, 2);
+  assert.deepEqual(
+    scheduled[1].map((item) => item.id),
+    ["u", "c", "a"],
+  );
+});