@cueloop/schema 0.1.0-alpha.76 → 0.1.0-alpha.78

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/schema",
-  "version": "0.1.0-alpha.76",
+  "version": "0.1.0-alpha.78",
   "description": "The Thread primitive: types, markdown block model, quote-primary anchors, feedback serialization",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {

package/src/anchor.test.ts

@@ -320,3 +320,75 @@ so a crash can never leave a torn file on disk.
     expect(resolved?.endBlockIndex).toBe(secondBullet - 1);
   });
 });
+
+describe("fuzzy work budget", () => {
+  function largePlan(paragraphs: number): string {
+    const lines = ["# Plan", ""];
+
+    for (let index = 0; index < paragraphs; index++) {
+      lines.push(
+        `This is paragraph number ${index} describing the migration of the session store and its atomic write path in enough prose to be a realistic block a reviewer might quote.`,
+        "",
+      );
+    }
+
+    return lines.join("\n");
+  }
+
+  test("a stale anchor over a large plan stays bounded across all its blocks", () => {
+    // Arrange - a 160-block plan whose quoted paragraph was edited so the exact text is gone,
+    // forcing the fuzzy tier over every block; a per-block budget would freeze for many seconds
+    const blocks = parseBlocks(largePlan(160));
+    const quoted = Math.floor(blocks.length / 2);
+    const anchor = makeAnchor(blocks, quoted, 0, Math.min(blocks[quoted]!.text.length, 140));
+    const edited = blocks.map((block) => ({
+      ...block,
+      text: block.text.replaceAll("migration", "rollout").replaceAll("session", "record"),
+    }));
+
+    // Act
+    const started = Date.now();
+    const resolved = resolveAnchor(anchor, edited);
+    const elapsed = Date.now() - started;
+
+    // Assert - it rebinds via the fuzzy tier, and one shared budget keeps it far under a freeze
+    expect(resolved?.strategy).toBe("fuzzy");
+    expect(elapsed).toBeLessThan(2000);
+  });
+
+  test("still binds when a distinctive quote moved down a few blocks and was edited", () => {
+    // Arrange - a distinctive quote among unrelated blocks; the agent inserts paragraphs above it
+    // (shifting it down) and edits one word, so exact/normalized miss and the outward scan must
+    // reach the shifted block before the shared budget runs out
+    const original =
+      "The canonical migration store commits every session write atomically along one path.";
+    const plan = (target: string): string => {
+      const lines = ["# Plan", ""];
+
+      for (let index = 0; index < 40; index++) {
+        lines.push(
+          index === 20
+            ? target
+            : `Filler paragraph ${index} covers an unrelated topic in its own words.`,
+          "",
+        );
+      }
+
+      return lines.join("\n");
+    };
+    const before = parseBlocks(plan(original));
+    const quoted = before.findIndex((block) => block.text === original);
+    const anchor = makeAnchor(before, quoted, 0, original.length);
+    const edited = original.replace("atomically", "carefully");
+    const shifted = parseBlocks(
+      plan(edited).replace("# Plan\n", "# Plan\n\nInserted A.\n\nInserted B.\n\nInserted C.\n"),
+    );
+
+    // Act
+    const resolved = resolveAnchor(anchor, shifted);
+
+    // Assert - rebinds via fuzzy onto the shifted block, not orphaned or bound to a neighbour
+    expect(resolved?.strategy).toBe("fuzzy");
+    expect(shifted[resolved!.blockIndex]!.text).toBe(edited);
+  });
+});

package/src/anchor.ts

@@ -18,7 +18,7 @@
 
 import type { Anchor } from "./types";
 import { type Block, stripLeadingBlockMarker } from "./markdown";
-import { fuzzyFindBestMatch } from "./fuzzy";
+import { fuzzyFindBestMatch, newFuzzyBudget } from "./fuzzy";
 
 /** Characters of surrounding text captured as prefix/suffix selectors. */
 const ANCHOR_CONTEXT_CHARS = 24;
@@ -139,7 +139,26 @@ function findExactCandidates(anchor: Anchor, blocks: Block[], quote: string): Ca
  */
 const FUZZY_CONTEXT_TIE_BREAK = 0.01;
 
-/** The best fuzzy window per block, ranked by similarity with context as a tiebreak. */
+/** Block indices to scan, spiralling out from the anchor's hinted block: hint, hint+1, hint-1, ... */
+function blockScanOrder(hint: number | undefined, count: number): number[] {
+  if (count <= 0) return [];
+  const first = Number.isInteger(hint) ? Math.min(Math.max(hint!, 0), count - 1) : 0;
+  const order = [first];
+
+  for (const step of Array.from({ length: count - 1 }, (_unused, index) => index + 1)) {
+    if (first + step < count) order.push(first + step);
+    if (first - step >= 0) order.push(first - step);
+  }
+
+  return order;
+}
+
+/**
+ * The best fuzzy window per block, ranked by similarity with context as a tiebreak. One work budget
+ * is shared across every block scan, so a stale anchor costs a single budget total, not one per
+ * block. Blocks are scanned outward from the anchor's hint, so a quote nudged a few blocks by an
+ * edit is reached before the budget runs out; a passage that moved far or is truly gone orphans.
+ */
 function findFuzzyCandidates(
   anchor: Anchor,
   blocks: Block[],
@@ -147,17 +166,21 @@ function findFuzzyCandidates(
   minimumSimilarity: number,
 ): Candidate[] {
   const candidates: Candidate[] = [];
+  const budget = newFuzzyBudget();
 
-  blocks.forEach((block, blockIndex) => {
-    const match = fuzzyFindBestMatch(needle, block.text, minimumSimilarity);
+  for (const blockIndex of blockScanOrder(anchor.blockIndex, blocks.length)) {
+    const block = blocks[blockIndex]!;
+    const match = fuzzyFindBestMatch(needle, block.text, minimumSimilarity, budget);
 
-    if (match === null) return;
-    const score =
-      match.similarity +
-      contextScore(anchor, blockIndex, block, match.start, match.end) * FUZZY_CONTEXT_TIE_BREAK;
+    if (match !== null) {
+      const score =
+        match.similarity +
+        contextScore(anchor, blockIndex, block, match.start, match.end) * FUZZY_CONTEXT_TIE_BREAK;
 
-    candidates.push({ blockIndex, start: match.start, end: match.end, score });
-  });
+      candidates.push({ blockIndex, start: match.start, end: match.end, score });
+    }
+    if (budget.remaining <= 0) break;
+  }
 
   return candidates;
 }

package/src/fuzzy.ts

@@ -63,25 +63,43 @@ export function similarityRatio(left: string, right: string): number {
 }
 
 /**
- * Character comparisons this scan may spend before it gives up and returns the
- * best window found so far (or null). The scan is O(haystack * needle^3) - a
+ * Character comparisons a fuzzy search may spend before it gives up and returns
+ * the best window found so far (or null). The scan is O(haystack * needle^3) - a
  * long quote fuzzed over a long document (a stale multi-block anchor whose text
  * is gone) would otherwise pin the CPU for a minute; a passage that is truly gone
  * is better left orphaned than fuzzed. Small everyday quotes never approach it.
  */
 const FUZZY_WORK_BUDGET = 150_000_000;
 
+/**
+ * A mutable work allowance shared across a group of fuzzy searches. Resolving one
+ * anchor scans every block, so a per-call cap would still let a stale multi-block
+ * anchor spend budget x blocks; sharing one budget across those scans bounds the
+ * whole anchor to a single budget, not one per block.
+ */
+export interface FuzzyBudget {
+  remaining: number;
+}
+
+/** A fresh work allowance for one anchor's fuzzy search across its blocks. */
+export function newFuzzyBudget(): FuzzyBudget {
+  return { remaining: FUZZY_WORK_BUDGET };
+}
+
 /**
  * Find the haystack window most similar to the needle, or null when nothing
  * clears `minimumSimilarity`. Windows range around the needle length so the
  * match tolerates a few inserted or deleted characters, not only substitutions.
  * Ties keep the earliest window. Offsets index the haystack directly. The scan
- * stops once it has spent `FUZZY_WORK_BUDGET`, returning the best window so far.
+ * spends from `budget` (its own single-budget allowance by default) and stops
+ * once the budget is exhausted, returning the best window so far - so a caller
+ * scanning many blocks can pass one budget to bound them together.
  */
 export function fuzzyFindBestMatch(
   needle: string,
   haystack: string,
   minimumSimilarity: number,
+  budget: FuzzyBudget = newFuzzyBudget(),
 ): FuzzyMatch | null {
   if (needle === "" || haystack === "") return null;
 
@@ -90,7 +108,6 @@ export function fuzzyFindBestMatch(
   const maximumWindowLength = needle.length + lengthTolerance;
 
   let bestMatch: FuzzyMatch | null = null;
-  let remainingWork = FUZZY_WORK_BUDGET;
 
   for (let start = 0; start < haystack.length; start++) {
     for (
@@ -98,9 +115,9 @@ export function fuzzyFindBestMatch(
       windowLength <= maximumWindowLength && start + windowLength <= haystack.length;
       windowLength++
     ) {
-      // each window costs a needle x window edit-distance pass; spend that from the budget
-      remainingWork -= needle.length * windowLength;
-      if (remainingWork <= 0) return bestMatch;
+      // each window costs a needle x window edit-distance pass; spend that from the shared budget
+      budget.remaining -= needle.length * windowLength;
+      if (budget.remaining <= 0) return bestMatch;
       const window = haystack.slice(start, start + windowLength);
       const similarity = similarityRatio(needle, window);
 

package/src/history.ts

@@ -1,5 +1,5 @@
 /**
- * A review session's history as an append-only tree of entries. Each entry
+ * A thread's history as an append-only tree of entries. Each entry
  * points at its parent; a branch is a named tip; the active path is the chain
  * from the current branch's tip back to the root. Nothing is ever deleted:
  * navigating moves a tip, a comment removal is its own entry, a fork copies a

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./types";
 export * from "./participants";
+export * from "./share-access";
 export * from "./markdown";
 export * from "./inline";
 export * from "./working-copy";

package/src/participants.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { registerParticipant } from "./participants";
+import { registerParticipant, registeredGithubLogin } from "./participants";
 import { SCHEMA_VERSION, type Thread } from "./types";
 
 function emptySession(): Thread {
@@ -55,4 +55,51 @@ describe("registerParticipant", () => {
     // Assert
     expect(next.participants).toEqual([{ id: "SHA256:ana", provider: "ssh", name: "Ana" }]);
   });
+
+  test("records a verified github source with its login handle", () => {
+    // Act
+    const next = registerParticipant(emptySession(), "SHA256:ana", "Ana", {
+      provider: "github",
+      handle: "ana",
+    });
+
+    // Assert
+    expect(next.participants).toEqual([
+      { id: "SHA256:ana", provider: "github", name: "Ana", handle: "ana" },
+    ]);
+  });
+
+  test("a later nameless write preserves the github provider and handle", () => {
+    // Arrange
+    const verified = registerParticipant(emptySession(), "SHA256:ana", "Ana", {
+      provider: "github",
+      handle: "ana",
+    });
+
+    // Act
+    const next = registerParticipant(verified, "SHA256:ana");
+
+    // Assert
+    expect(next.participants).toEqual([
+      { id: "SHA256:ana", provider: "github", name: "Ana", handle: "ana" },
+    ]);
+  });
+});
+
+describe("registeredGithubLogin", () => {
+  test("returns the handle a fingerprint verified on a past visit", () => {
+    const session = registerParticipant(emptySession(), "SHA256:ana", "Ana", {
+      provider: "github",
+      handle: "ana-gh",
+    });
+
+    expect(registeredGithubLogin(session, "SHA256:ana")).toBe("ana-gh");
+  });
+
+  test("returns undefined for an ssh-only or unknown participant", () => {
+    const session = registerParticipant(emptySession(), "SHA256:ana", "Ana");
+
+    expect(registeredGithubLogin(session, "SHA256:ana")).toBeUndefined();
+    expect(registeredGithubLogin(session, "SHA256:unknown")).toBeUndefined();
+  });
 });

package/src/participants.ts

@@ -13,17 +13,34 @@ import type { Identity, Thread } from "./types";
  * rail renders anonymous) and never erases a name a past visit set. Immutable:
  * the input session is not mutated.
  */
-export function registerParticipant(session: Thread, author: string, name?: string): Thread {
+export interface ParticipantSource {
+  provider: "ssh" | "github";
+  handle?: string;
+}
+
+export function registeredGithubLogin(session: Thread, author: string): string | undefined {
+  const existing = (session.participants ?? []).find((participant) => participant.id === author);
+
+  return existing?.provider === "github" ? existing.handle : undefined;
+}
+
+export function registerParticipant(
+  session: Thread,
+  author: string,
+  name?: string,
+  source?: ParticipantSource,
+): Thread {
   const participants = session.participants ?? [];
   const existing = participants.find((participant) => participant.id === author);
   const trimmed = name?.trim();
 
-  if (existing && !trimmed) return session;
-  const next: Identity = {
-    id: author,
-    provider: "ssh",
-    ...(trimmed ? { name: trimmed } : existing?.name ? { name: existing.name } : {}),
-  };
+  if (existing && !trimmed && !source) return session;
+  const resolvedName = trimmed ?? existing?.name;
+  const resolvedHandle = source?.handle ?? existing?.handle;
+  const next: Identity = { id: author, provider: source?.provider ?? existing?.provider ?? "ssh" };
+
+  if (resolvedName) next.name = resolvedName;
+  if (resolvedHandle) next.handle = resolvedHandle;
 
   return {
     ...session,

package/src/share-access.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { isShareViewerAllowed } from "./share-access";
+
+describe("isShareViewerAllowed", () => {
+  test("an unauthenticated viewer is refused", () => {
+    expect(isShareViewerAllowed({ githubLogins: ["octocat"] }, undefined)).toBe(false);
+  });
+
+  test("a member is admitted, case-insensitively", () => {
+    expect(isShareViewerAllowed({ githubLogins: ["OctoCat"] }, "octocat")).toBe(true);
+  });
+
+  test("a non-member is refused", () => {
+    expect(isShareViewerAllowed({ githubLogins: ["octocat"] }, "hubot")).toBe(false);
+  });
+
+  test("an empty allowlist admits no one", () => {
+    expect(isShareViewerAllowed({ githubLogins: [] }, "octocat")).toBe(false);
+  });
+});

package/src/share-access.ts

@@ -0,0 +1,13 @@
+/** Whether a github login may view a private share; membership is case-insensitive and an unauthenticated viewer is never allowed. */
+
+import type { ShareAccess } from "./types";
+
+export function isShareViewerAllowed(
+  access: ShareAccess,
+  githubLogin: string | undefined,
+): boolean {
+  if (githubLogin === undefined) return false;
+  const login = githubLogin.toLowerCase();
+
+  return access.githubLogins.some((allowed) => allowed.toLowerCase() === login);
+}

package/src/types.ts

@@ -8,7 +8,7 @@ import type { SessionHistory } from "./history";
 
 export const SCHEMA_VERSION = "1";
 
-/** A workspace is a repo/branch context holding review sessions. */
+/** A workspace is a repo/branch context holding threads. */
 export interface WorkspaceKey {
   repoRoot: string;
   branch: string;
@@ -19,7 +19,7 @@ export interface WorkspaceKey {
 }
 
 /**
- * What kind of artifact a review session holds. `plan` and `reply` are both
+ * What kind of artifact a thread holds. `plan` and `reply` are both
  * markdown documents (see isMarkdownArtifact) - a plan is a proposal written
  * forward, a reply is the agent's previous message pulled back for review.
  * `diff` is a unified-diff patch; `prototype` is a component design doc (API /
@@ -224,14 +224,19 @@ export type SessionStatus = "pending" | "resolved";
 export interface Identity {
   /** Stable identity key; equals an annotation's `author`. */
   id: string;
-  /** Identity source. One value today; widen the union when OAuth lands. */
-  provider: "ssh";
+  /** Identity source: the SSH key that authored, or a verified GitHub login. */
+  provider: "ssh" | "github";
   /** Display name; absent = the collaborator stayed anonymous. */
   name?: string;
   /** Provider handle: a github login, an email, or a short fingerprint. */
   handle?: string;
 }
 
+/** Owner-set access control for a private share: only these GitHub logins may open it. Absent = a public share. */
+export interface ShareAccess {
+  githubLogins: string[];
+}
+
 export interface Thread {
   schemaVersion: string;
   id: string;
@@ -278,6 +283,8 @@ export interface Thread {
   shareBranch?: string;
   /** SSH fingerprint that created the share; the gateway stamps it to gate pulls. */
   owner?: string;
+  /** Owner-set allowlist of GitHub logins for a private share; absent = public. */
+  access?: ShareAccess;
   /**
    * Identities that authored annotations here, keyed by id (union-by-id, like
    * annotations). The gateway records a collaborator's identity and chosen name;
@@ -286,9 +293,6 @@ export interface Thread {
   participants?: Identity[];
 }
 
-/** @deprecated use Thread */
-export type ReviewSession = Thread;
-
 /** comment and request_changes both map to deny in agent-native contracts. */
 export function verdictAllows(kind: VerdictKind): boolean {
   return kind === "approve";