feat(bus): add subscribeOnce helper (strictly decomposed from B-0459)

[AceHack]

Strict decomposition of B-0459 (#3643). This PR only contains the subscribeOnce bus helper, leaving the subscriber implementation for a subsequent slice.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aa8a424403

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR aims to introduce a new TypeScript helper subscribeOnce under tools/bus/ to process unseen bus envelopes once per surface by persisting “seen” IDs, as a strictly decomposed slice of B-0459.

Changes:

• Adds tools/bus/subscribe.ts implementing subscribeOnce.
• Adds tools/bus/subscribe.test.ts with Bun tests covering “seen” persistence and retry-on-handler-failure behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
tools/bus/subscribe.ts	Introduces subscribeOnce helper that tracks processed envelope IDs via a per-surface JSON file.
tools/bus/subscribe.test.ts	Adds Bun tests for the new helper’s seen-state and retry semantics.

Comments suppressed due to low confidence (4)

tools/bus/subscribe.ts:20

• P1: surface is used directly in the filename seen-${surface}.json. If surface contains / or other path separators, this will create nested paths and writeFileSync will fail (or create unexpected files). Validate/sanitize surface to a safe filename component (e.g., allow [A-Za-z0-9_-] only, or encode).

  ensureDir();
  const seenFile = join(BUS_DIR, `seen-${surface}.json`);
  let seenIds: Set<string>;
  

tools/bus/subscribe.ts:10

• P2: The docstring says this writes to a “surface-specific seen.json file”, but the implementation writes seen-${surface}.json. Update the comment to match the actual filename so callers can locate/debug the state file.

/**
 * Reads envelopes from the bus matching the given topic and recipient,
 * calls the handler for each unseen envelope, and marks them as seen
 * in a surface-specific seen.json file.
 */

tools/bus/subscribe.test.ts:4

• P0: Topic is imported but never used, and the mock(async (env) => {}) callback parameter is unused. With noUnusedLocals/noUnusedParameters enabled in tsconfig.json, this will fail the tsc --noEmit gate. Remove the unused import and either remove the unused parameter or rename it to _env.

import { describe, expect, test, mock } from "bun:test";
import { subscribeOnce } from "./subscribe";
import type { MessageEnvelope, Topic } from "./types";
import { rmSync } from "node:fs";

tools/bus/subscribe.test.ts:9

• P2: The describe label references “B-0449 slice 5”, but the PR is for B-0459. If this is copy/pasted, update the string so test output/reporting matches the actual slice/row.

describe("bus subscribeOnce (B-0449 slice 5)", () => {
  const seenFile = join(BUS_DIR, "seen-test-surface.json");

[AceHack]

Lior Antigravity Check: Decomposition verified. Needs Copilot feedback addressed for merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5618091c2d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 36b6a35b0b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (2)

tools/bus/subscribe.ts:35

• P1: The comment says JSON corruption should re-throw, but a wrong-but-valid JSON shape (e.g., {}) will parse successfully and then be treated as an empty seen-set via Array.isArray(data) ? data : []. That silently drops seen-state and can cause unexpected re-processing; consider throwing (or at least logging loudly) when the file’s JSON isn’t the expected array of ids.

  // Single readFileSync + ENOENT-aware catch. Other errors (permission,
  // JSON corruption) re-throw so we never silently drop seen-state and
  // re-deliver already-handled envelopes.
  try {
    const data = JSON.parse(readFileSync(seenFile, "utf8"));
    seenIds = new Set(Array.isArray(data) ? data : []);
  } catch (err) {

tools/bus/subscribe.ts:66

• P1: writeFileSync failures when persisting the seen-set are swallowed (only console.error). If the seen file can’t be written (permissions/disk full), the function still returns success after running handlers, which will cause repeated deliveries on the next tick. Consider surfacing this failure to the caller (throw/return error) so the poller can fail fast rather than silently degrading semantics.

  if (newlySeen) {
    try {
      writeFileSync(seenFile, JSON.stringify(Array.from(seenIds), null, 2));
    } catch (err) {
      console.error(`[subscribeOnce] Failed to write seen file:`, err);
    }

[AceHack]

Codex P2 thread (propagate seen-file write failures) addressed in 5b490ba:

• subscribe.ts: removed the swallow-and-log path; writeFileSync errors now propagate to the caller (symmetric with the existing read-side discipline)
• subscribe.test.ts: added propagates seen-file write failures to caller — pre-creates seen file as 0444 so read succeeds + write throws EACCES; expect(...).rejects.toThrow()

Also merged origin/main into the branch (it was branched before tools/bus/bus.ts existed). Tests pass locally (3/3).