packages/backend/scripts/migrate-yorkie-worksheet-shape.d.ts (1)

1-1: Clarify the purpose of this empty declaration file.

An empty export {} in a .d.ts file is unusual. If this is a CLI script that shouldn't be imported as a library, consider whether this declaration file is needed at all, or add a comment explaining its purpose (e.g., satisfying module resolution or preventing accidental imports).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/backend/scripts/migrate-yorkie-worksheet-shape.d.ts` at line 1, The
file migrate-yorkie-worksheet-shape.d.ts currently only contains an empty
"export {}" which is unclear; either delete this declaration file if it serves
no purpose, or replace it with a short explanatory comment and a clearer intent
(e.g., explain it exists to force module scope / prevent accidental imports or
to satisfy TypeScript module resolution), or change it to a proper declaration
(declare module '...' { /* types */ }) if it is intended to provide typings;
update the file migrate-yorkie-worksheet-shape.d.ts accordingly and ensure the
change matches the intended use of the CLI script or module.

packages/sheet/src/view/spreadsheet.ts (1)

1-12: Make the core-types import type-only.

Every symbol imported from ../model/core/types is used exclusively in type positions (parameter types, return types, and type annotations), so converting to a type-only import accurately reflects the new core/worksheet boundary.

♻️ Proposed fix

-import {
+import type {
   Axis,
   BorderPreset,
   CellStyle,
   ConditionalFormatRule,
   FilterCondition,
   GridResolver,
   Range,
   Ref,
   SelectionType,
 } from '../model/core/types';
 import { Sheet } from '../model/worksheet/sheet';

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/sheet/src/view/spreadsheet.ts` around lines 1 - 12, The import from
../model/core/types should be changed to a type-only import because all symbols
(Axis, BorderPreset, CellStyle, ConditionalFormatRule, FilterCondition,
GridResolver, Range, Ref, SelectionType) are used only for typing; update the
import line in spreadsheet.ts to use an "import type { ... } from
'../model/core/types';" form so the core/worksheet boundary is preserved and
runtime bundling won't include these types.

packages/sheet/src/view/formulabar.ts (1)

2-2: Use a type-only import for Sheet.

Sheet is only referenced in type positions (lines 12 and 80), so converting to import type removes an unnecessary runtime dependency between the view and worksheet layers.

♻️ Proposed fix

-import { Sheet } from '../model/worksheet/sheet';
+import type { Sheet } from '../model/worksheet/sheet';

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/sheet/src/view/formulabar.ts` at line 2, Replace the runtime import
of Sheet with a type-only import: change "import { Sheet } from
'../model/worksheet/sheet';" to "import type { Sheet } from
'../model/worksheet/sheet';" in formulabar.ts, ensuring that all references to
Sheet (e.g., the type annotations used in the form bar functions/variables)
remain type-only and that no runtime usage of Sheet exists in the file so the
compiler emits no runtime import.

docs/tasks/active/20260314-yorkie-worksheet-shape-migration-lessons.md (1)

6-6: Hyphenate compound adjective for clarity.

Consider changing “side-effect free” to “side-effect-free” in Line 6.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/tasks/active/20260314-yorkie-worksheet-shape-migration-lessons.md` at
line 6, The phrase "side-effect free" should be hyphenated as the compound
adjective "side-effect-free"; update the text in the document where the label
sentence contains "side-effect free" so it reads "side-effect-free" to clarify
the compound modifier.

docs/tasks/active/20260313-crdt-structural-concurrency-retrospective-todo.md (1)

3-4: Use hyphenated compound modifiers for readability.

Consider “stable-grid-based” and “visual-index-based” in these sections for cleaner technical prose.

Also applies to: 36-39

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/tasks/active/20260313-crdt-structural-concurrency-retrospective-todo.md`
around lines 3 - 4, Replace non-hyphenated compound modifiers with hyphenated
forms for clarity: change occurrences of "stable grid based" to
"stable-grid-based" and "visual index based" to "visual-index-based" throughout
the document (including the phrases in the current section and the lines
referenced as 36-39); update any variants like "stable-grid based" or
"visual-index based" to the fully hyphenated form to ensure consistent, readable
technical prose.

docs/tasks/active/20260313-backend-dev-start-failure-todo.md (1)

67-70: Make verification commands context-stable.

Line 69 switches to a bare tsc --build ... command, which is ambiguous outside packages/backend. Consider using the same pnpm --filter @wafflebase/backend exec ... pattern (or explicitly state the working directory) so the repro steps are deterministic.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/tasks/active/20260313-backend-dev-start-failure-todo.md` around lines 67
- 70, The second verification step uses a bare "tsc --build tsconfig.build.json
--force --listEmittedFiles" which is ambiguous; update that line to either use
the same pnpm wrapper (pnpm --filter `@wafflebase/backend` exec tsc --build
tsconfig.build.json --force --listEmittedFiles) or explicitly state "run from
packages/backend" so the commands are deterministic and context-stable in the
repro steps.

packages/frontend/tests/helpers/two-user-yorkie.ts (2)

63-86: Add exhaustiveness check for operation kinds.

The switch statement handles known operation kinds but doesn't have a default case. If a new operation kind is added to ConcurrencyOp, this function will silently do nothing rather than failing fast.

♻️ Proposed fix to add exhaustiveness check

 async function applyStoreOp(store: YorkieStore, op: ConcurrencyOp): Promise<void> {
   switch (op.kind) {
     case "set-data": {
       const ref = parseRef(op.ref);
       const cell = op.value.startsWith("=")
         ? { f: op.value }
         : { v: op.value };
       await store.set(ref, cell);
       return;
     }
     case "insert-rows":
       await store.shiftCells("row", op.index, op.count ?? 1);
       return;
     case "delete-rows":
       await store.shiftCells("row", op.index, -(op.count ?? 1));
       return;
     case "insert-columns":
       await store.shiftCells("column", op.index, op.count ?? 1);
       return;
     case "delete-columns":
       await store.shiftCells("column", op.index, -(op.count ?? 1));
       return;
+    default: {
+      const _exhaustive: never = op;
+      throw new Error(`Unknown operation kind: ${(_exhaustive as ConcurrencyOp).kind}`);
+    }
   }
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/frontend/tests/helpers/two-user-yorkie.ts` around lines 63 - 86, The
switch in applyStoreOp handling ConcurrencyOp kinds is non-exhaustive; add a
default branch that fails fast for unknown kinds (so new variants don't silently
no-op). Update applyStoreOp to include a default case that asserts
exhaustiveness (e.g., cast op to never or throw an Error) and surface the
unexpected op.kind; reference applyStoreOp, ConcurrencyOp, parseRef,
YorkieStore.set and YorkieStore.shiftCells to locate where to add the
default/exhaustive check.

---

46-48: Consider improving type safety for YorkieStore instantiation.

The as never cast bypasses type checking. This works but could mask type mismatches if YorkieStore constructor signature changes.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/frontend/tests/helpers/two-user-yorkie.ts` around lines 46 - 48, The
helper createStore currently silences type checking by casting doc to never;
update it to preserve type-safety by making createStore generic and casting via
unknown (or typing the parameter to the YorkieStore constructor type). For
example, change function createStore(doc: T) to a generic signature (e.g.,
function createStore<T>(doc: T): YorkieStore and cast doc as unknown as
ConstructorParamType) so the YorkieStore instantiation (new YorkieStore(...)) no
longer uses "as never" and mismatched shapes are caught by the compiler; locate
the createStore function and the YorkieStore constructor usage to apply this
change.

packages/frontend/src/app/spreadsheet/yorkie-worksheet-axis.ts (1)

72-93: Consider documenting the 1-based index convention.

The function uses Math.max(0, index - 1) to convert from 1-based to 0-based indices. This convention should be documented in the function signature or a comment to prevent confusion for callers.

📝 Suggested documentation

+/**
+ * Insert new rows or columns into the worksheet.
+ * `@param` ws - The worksheet to modify
+ * `@param` axis - Whether to insert rows or columns
+ * `@param` index - 1-based position to insert at (1 = before first element)
+ * `@param` count - Number of rows/columns to insert
+ */
 export function insertYorkieWorksheetAxis(
   ws: Worksheet,
   axis: Axis,
   index: number,
   count: number,
 ): void {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/frontend/src/app/spreadsheet/yorkie-worksheet-axis.ts` around lines
72 - 93, Add clear documentation that the parameter index is 1-based and the
function converts it to 0-based via Math.max(0, index - 1); update the function
comment or JSDoc for insertYorkieWorksheetAxis to state the 1-based indexing
convention (for both row and col axes) and note that ensureAxisLength and the
splice call expect the converted 0-based index, so callers should pass 1-based
positions (use index = 1 for the first position).

packages/backend/scripts/copy-yorkie-documents.js (1)

104-126: Document mongosh dependency requirement.

The fetchExistingYorkieKeys function shells out to mongosh. If the tool isn't installed, execFileSync will throw with a potentially confusing error. Consider adding a pre-flight check or documenting this dependency in the usage text.

💡 Proposed usage text update (apply to source .ts file)

 function usage() {
     return `Usage:
   pnpm --filter `@wafflebase/backend` exec tsx scripts/copy-yorkie-documents.ts \\
     --database-url <postgres-url> \\
     --mongo-url <mongo-url> \\
     --project-public-key <public-key> \\
     --source-rpc-addr <source-rpc-addr> \\
     --source-api-key <source-api-key> \\
     --target-rpc-addr <target-rpc-addr> \\
-    [--limit <count>] [--document <id> ...]`;
+    [--limit <count>] [--document <id> ...]
+
+Requires: mongosh (MongoDB Shell) to be installed and in PATH.`;
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/backend/scripts/copy-yorkie-documents.js` around lines 104 - 126,
The function fetchExistingYorkieKeys currently calls mongosh via execFileSync
and will throw a confusing error if mongosh isn't installed; add a pre-flight
check before invoking execFileSync (e.g., call execFileSync('mongosh',
['--version']) or spawnSync to verify availability and a zero exit code) and
replace the raw exception with a clear, user-facing error that explains the
missing mongosh dependency and points to installation instructions; update any
usage/help text in the same file to document the mongosh requirement and refer
to the new check so users see an actionable message instead of the low-level
exception.

packages/sheet/src/model/workbook/worksheet-grid.ts (1)

88-89: Use for...of to avoid linter warning about callback return values.

The forEach callbacks implicitly return the result of Map.set(), which triggers Biome's useIterableCallbackReturn rule. While functionally correct, switching to for...of silences the linter and is arguably more readable.

♻️ Proposed refactor

-  rowOrder.forEach((rowId, index) => rowIndex.set(rowId, index + 1));
-  colOrder.forEach((colId, index) => colIndex.set(colId, index + 1));
+  for (const [index, rowId] of rowOrder.entries()) {
+    rowIndex.set(rowId, index + 1);
+  }
+  for (const [index, colId] of colOrder.entries()) {
+    colIndex.set(colId, index + 1);
+  }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/sheet/src/model/workbook/worksheet-grid.ts` around lines 88 - 89,
The linter flags useIterableCallbackReturn because rowOrder.forEach and
colOrder.forEach callbacks return Map.set(); replace both forEach uses with
explicit for...of loops to iterate arrays and call rowIndex.set(rowId, index +
1) and colIndex.set(colId, index + 1) inside the loop bodies (use an index
counter or Array.prototype.entries() in the for...of) so that rowOrder,
colOrder, rowIndex.set, and colIndex.set remain the same but no callback return
value is produced.

packages/backend/scripts/copy-yorkie-documents.ts (2)

370-373: Add error handling for individual document copy failures.

If copyDocument throws for one document, the entire loop aborts and remaining documents are not processed. Consider catching errors per-document to continue with others and report failures at the end.

🛡️ Proposed error handling improvement

+    const failures: Array<{ key: string; error: unknown }> = [];
     for (const key of existingKeys) {
-      await copyDocument(sourceClient, targetClient, key);
-      console.log(`copied ${key}`);
+      try {
+        await copyDocument(sourceClient, targetClient, key);
+        console.log(`copied ${key}`);
+      } catch (error) {
+        console.error(`failed to copy ${key}:`, error instanceof Error ? error.message : error);
+        failures.push({ key, error });
+      }
     }
+
+    if (failures.length > 0) {
+      console.log(`\nFailed to copy ${failures.length} document(s).`);
+    }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/backend/scripts/copy-yorkie-documents.ts` around lines 370 - 373,
The loop over existingKeys currently awaits copyDocument(sourceClient,
targetClient, key) directly so a thrown error aborts the whole process; wrap the
per-key call in a try/catch inside the for loop (the loop that iterates
existingKeys and calls copyDocument) to catch and log errors for that key
(include the key and error message), push failed keys/errors into a local
failures array, continue processing remaining keys, and after the loop report a
summary (e.g., log or throw a single aggregated error) if failures is non-empty
so callers can see which documents failed.

---

362-362: Consider using a Set for O(1) membership checks.

existingKeys is an array, and Array.includes() is O(n) per call. Converting to a Set would make the filter operation more efficient, especially with many documents.

♻️ Proposed optimization

-    const missingKeys = candidateKeys.filter((key) => !existingKeys.includes(key));
+    const existingKeySet = new Set(existingKeys);
+    const missingKeys = candidateKeys.filter((key) => !existingKeySet.has(key));

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/backend/scripts/copy-yorkie-documents.ts` at line 362, The filter
that builds missingKeys uses Array.includes on existingKeys which is O(n) per
check; change to create a Set from existingKeys (e.g., const existingKeySet =
new Set(existingKeys)) and then use existingKeySet.has(key) inside the
candidateKeys.filter callback to get O(1) membership checks and improve
performance (update the reference in the filter that currently uses
existingKeys.includes).

packages/sheet/src/model/workbook/worksheet-record.ts (1)

71-81: Silent fallback for malformed keys may hide bugs.

When the separator is not found, returning { rowId: '', colId: '' } silently hides malformed input. Callers may not expect empty strings and could produce unexpected behavior. Consider whether throwing an error or returning null would be safer for debugging.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/sheet/src/model/workbook/worksheet-record.ts` around lines 71 - 81,
The function parseWorksheetCellKey silently returns empty strings when
WorksheetCellKeySeparator isn't found which can hide malformed input; update
parseWorksheetCellKey to fail fast by throwing a descriptive Error (include the
invalid key and the expected WorksheetCellKeySeparator) instead of returning
{rowId: '', colId: ''}, and update any callers or types to handle the thrown
error (or alternatively change the return type to nullable and return null
consistently if you prefer non-throwing behavior); locate parseWorksheetCellKey
and replace the fallback branch with a clear error throw (or null return) and
ensure tests/call sites handle the new behavior.

packages/backend/src/yorkie/worksheet-shape-migration.spec.ts (1)

252-258: Consider adding more unsupported shape test cases.

The current test only covers a simple object with unrecognized keys. Consider adding edge cases like arrays, primitives, or nested structures that don't match any expected shape.

💡 Additional test cases to consider

it('throws for array roots', () => {
  expect(() => migrateYorkieWorksheetShape([])).toThrow(
    'Unsupported Yorkie spreadsheet document shape',
  );
});

it('throws for primitive roots', () => {
  expect(() => migrateYorkieWorksheetShape('string' as never)).toThrow();
});

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/backend/src/yorkie/worksheet-shape-migration.spec.ts` around lines
252 - 258, Add extra negative test cases for migrateYorkieWorksheetShape to
cover more unsupported shapes: include at least one test that passes an array
root (e.g., []), one that passes a primitive root (e.g., 'string' cast as
never), and optionally a nested unexpected structure, each asserting they throw
'Unsupported Yorkie spreadsheet document shape' (or at least throw); update the
spec around the existing it('throws for unsupported shapes') block to add these
new it(...) cases referencing migrateYorkieWorksheetShape so the function's
validation covers arrays, primitives, and nested invalid inputs.

packages/sheet/test/helpers/concurrency-driver.ts (2)

24-45: Add exhaustiveness check for operation kinds.

The switch statement handles all current operation kinds but lacks a default case. If new operation kinds are added to ConcurrencyOp, this function would silently do nothing instead of failing fast.

♻️ Add exhaustiveness check

 export async function applyConcurrencyOp(
   sheet: Sheet,
   op: ConcurrencyOp,
 ): Promise<void> {
   switch (op.kind) {
     case 'set-data':
       await sheet.setData(parseRef(op.ref), op.value);
       return;
     case 'insert-rows':
       await sheet.insertRows(op.index, op.count ?? 1);
       return;
     case 'delete-rows':
       await sheet.deleteRows(op.index, op.count ?? 1);
       return;
     case 'insert-columns':
       await sheet.insertColumns(op.index, op.count ?? 1);
       return;
     case 'delete-columns':
       await sheet.deleteColumns(op.index, op.count ?? 1);
       return;
+    default: {
+      const _exhaustive: never = op;
+      throw new Error(`Unknown operation kind: ${(_exhaustive as ConcurrencyOp).kind}`);
+    }
   }
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/sheet/test/helpers/concurrency-driver.ts` around lines 24 - 45, The
switch in applyConcurrencyOp (function) covers current ConcurrencyOp kinds but
lacks an exhaustive default; add an explicit exhaustiveness check so new
ConcurrencyOp variants fail fast: either add a default branch that throws a
descriptive Error (e.g., `throw new Error('Unhandled ConcurrencyOp kind: ' + (op
as any).kind)`) or introduce/consume a utility like assertNever(value: never)
and call it in the default case to ensure the compiler enforces exhaustiveness
for ConcurrencyOp and surface unhandled kinds at runtime/compile time.

---

89-94: JSON.stringify comparison may have ordering issues.

Using JSON.stringify for snapshot comparison works but is sensitive to property ordering. If ConcurrencySnapshot properties are added in different orders, semantically equal snapshots would fail comparison.

💡 Consider deep equality check

For robustness, consider using a deep equality function or sorting keys before stringifying:

export function snapshotMatchesOneOf(
  actual: ConcurrencySnapshot,
  candidates: ConcurrencySnapshot[],
): boolean {
  const normalize = (obj: unknown) => JSON.stringify(obj, Object.keys(obj as object).sort());
  return candidates.some((candidate) => normalize(candidate) === normalize(actual));
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/sheet/test/helpers/concurrency-driver.ts` around lines 89 - 94, The
snapshotMatchesOneOf function currently compares snapshots with JSON.stringify
which can fail if object key order differs; update snapshotMatchesOneOf (working
with ConcurrencySnapshot) to perform a stable deep-equality comparison instead
of raw stringify — either by normalizing objects with a deterministic
JSON.stringify (use a normalize helper that sorts Object.keys(obj) in the
replacer) before comparing, or call a reliable deepEqual (e.g. lodash/isEqual)
to compare actual against each candidate; ensure the helper handles nested
objects consistently and use that in the candidates.some check.

packages/frontend/tests/app/spreadsheet/chart-utils.test.ts (1)

45-63: Use the shared document factory in this fixture helper.

buildDoc() hand-assembles the workbook envelope even though the canonical createSpreadsheetDocument() helper now owns those defaults. Reusing that factory will keep this test data aligned with future document-schema changes instead of maintaining a parallel constructor here.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/frontend/tests/app/spreadsheet/chart-utils.test.ts` around lines 45
- 63, The buildDoc helper manually constructs the spreadsheet envelope; replace
that with the shared factory createSpreadsheetDocument to keep test fixtures
aligned with canonical defaults—create the worksheet via createWorksheet(),
write cells with writeWorksheetCell(parseRef(...)), then call
createSpreadsheetDocument to produce the full document envelope and attach the
worksheet (or pass it into the factory if supported); update buildDoc to return
the result of createSpreadsheetDocument (or the factory result after assigning
tabs, tabOrder, and sheets) instead of hand-assembling the object so you avoid
duplicating schema defaults.

docs/tasks/active/20260314-ci-export-failure-todo.md (1)

1-4: Consider linking to the lessons learned document.

To improve navigation between related documentation, consider adding a reference to the lessons learned file where this investigation's key takeaway is captured.

📝 Suggested enhancement with cross-reference

 # CI Export Failure Investigation
 
 Investigate and fix the GitHub Actions failure caused by invalid runtime ESM
 exports from the `@wafflebase/sheet` barrel.
+
+> **Lesson captured:** [Barrel Files Must Separate Type-Only Exports From Runtime Exports](./20260314-ci-export-failure-lessons.md)
 
 ## Tasks

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/tasks/active/20260314-ci-export-failure-todo.md` around lines 1 - 4, Add
a cross-reference from this task doc ("CI Export Failure Investigation" in
20260314-ci-export-failure-todo.md) to the lessons-learned document: insert a
short sentence or markdown link after "Consider linking to the lessons learned
document." that points to the canonical lessons file (e.g.,
"docs/lessons/ci-export-failure-lessons.md" or whatever the repository's lessons
file is named), include link text like "See lessons learned" and ensure the link
is relative and uses standard Markdown so readers can navigate between the task
and the lessons-learned document.

docs/tasks/active/20260314-ci-export-failure-lessons.md (1)

1-9: Consider adding a cross-reference to the investigation workflow.

To improve discoverability, consider adding a reference to the related investigation workflow document at docs/tasks/active/20260314-ci-export-failure-todo.md. This would help readers find the full context and verification steps.

📝 Suggested enhancement with cross-reference

 # CI Export Failure Investigation — Lessons
+
+> See also: [CI Export Failure Investigation workflow](./20260314-ci-export-failure-todo.md)
 
 ## Barrel Files Must Separate Type-Only Exports From Runtime Exports

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/tasks/active/20260314-ci-export-failure-lessons.md` around lines 1 - 9,
Add a short cross-reference sentence and link to the related investigation
workflow document near the top of this note (under the "Barrel Files Must
Separate Type-Only Exports From Runtime Exports" heading) that points readers to
the CI export failure investigation/workflow (the "todo" workflow) so they can
follow the full investigation and verification steps; keep the wording concise
(one or two sentences), include the document title as link text, and place it
where readers scanning the lessons will notice it immediately.

packages/sheet/test/helpers/concurrency-driver.ts (1)

93-98: JSON.stringify comparison is acceptable but has a subtle ordering assumption.

Since ConcurrencySnapshot.cells is a Record<Sref, ...>, JSON.stringify will serialize keys in insertion order. This works correctly as long as both actual and candidate snapshots are built with the same key ordering (e.g., both using the same refs array via captureConcurrencySnapshot).

If manually constructed candidate snapshots in test cases have different key ordering, comparison could fail unexpectedly. For test helpers this is likely fine, but for extra robustness you could normalize key order before comparison.

🔧 Optional: Normalize key order for comparison

 export function snapshotMatchesOneOf(
   actual: ConcurrencySnapshot,
   candidates: ConcurrencySnapshot[],
 ): boolean {
-  return candidates.some((candidate) => JSON.stringify(candidate) === JSON.stringify(actual));
+  const normalize = (snap: ConcurrencySnapshot): string => {
+    const sortedCells = Object.keys(snap.cells)
+      .sort()
+      .reduce((acc, key) => ({ ...acc, [key]: snap.cells[key] }), {});
+    return JSON.stringify({ cells: sortedCells });
+  };
+  const actualStr = normalize(actual);
+  return candidates.some((candidate) => normalize(candidate) === actualStr);
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/sheet/test/helpers/concurrency-driver.ts` around lines 93 - 98, The
JSON.stringify comparison in snapshotMatchesOneOf can fail if Record keys are in
different insertion orders; update snapshotMatchesOneOf (and/or add a small
helper like normalizeSnapshot) to produce a deterministic representation by
sorting the keys of ConcurrencySnapshot.cells (e.g., iterate
Object.keys(snapshot.cells).sort() and build a new object with those ordered
keys, and likewise normalize any nested objects/arrays if needed) and then
compare JSON.stringify(normalizeSnapshot(candidate)) ===
JSON.stringify(normalizeSnapshot(actual)); this preserves existing behavior but
removes the ordering sensitivity when comparing ConcurrencySnapshot instances.

docs/design/spreadsheet-collaboration.md (1)

231-232: Minor grammar fix: hyphenate "top-level".

Per static analysis, "top level" should be hyphenated when used as a compound modifier.

📝 Suggested fix

-  - top level `tabs`, `tabOrder`, `sheets`
+  - top-level `tabs`, `tabOrder`, `sheets`

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/design/spreadsheet-collaboration.md` around lines 231 - 232, Change the
phrase "top level `tabs`, `tabOrder`, `sheets`" to use a hyphenated compound
modifier: "top-level `tabs`, `tabOrder`, `sheets`" so the document consistently
hyphenates "top-level" when used as a compound adjective (the worksheet-local
items `cells`, `rowOrder`, `colOrder`, `nextRowId`, `nextColId` remain
unchanged).

packages/sheet/src/index.ts (1)

127-141: Expose a callable alias for the default-document factory.

initialSpreadsheetDocument now reads like shared data, but this symbol now creates fresh state. Exporting a createInitialSpreadsheetDocument alias alongside the legacy name would make call sites much harder to misuse.

♻️ Suggested export shape

 import {
   DEFAULT_TAB_ID,
   DEFAULT_TAB_NAME,
   type ChartType,
   type SheetChart,
   type WorksheetFilterState,
   type Worksheet,
   type TabType,
   type SheetKind,
   type TabMeta,
   type SpreadsheetDocument,
   createWorksheet,
   createSpreadsheetDocument,
-  initialSpreadsheetDocument,
+  initialSpreadsheetDocument as createInitialSpreadsheetDocument,
 } from './model/workbook/worksheet-document';

 ...

   DEFAULT_TAB_ID,
   DEFAULT_TAB_NAME,
   createWorksheet,
   createSpreadsheetDocument,
-  initialSpreadsheetDocument,
+  createInitialSpreadsheetDocument,
+  createInitialSpreadsheetDocument as initialSpreadsheetDocument,
 };

As per coding guidelines, "Use descriptive variable and function names that clearly convey intent and purpose".

Also applies to: 212-216

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/sheet/src/index.ts` around lines 127 - 141, Export a clearly named
factory alias for the default-document creator: add and export
createInitialSpreadsheetDocument as a callable alias that forwards to the
existing initialSpreadsheetDocument factory so call sites use a verb-like name
instead of a value-like name; update any other "initial..." exports in this
module (the ones alongside createWorksheet and createSpreadsheetDocument) to
provide matching createX aliases as well so factories are consistently named.