Merge remote-tracking branch 'origin/master' into affan.khan/v2-checkpoint-as-briefcase

# Conflicts:
#	docs/changehistory/NextVersion.md

Co-authored-by: khanaffan <29756942+khanaffan@users.noreply.github.com>

Author: Copilot

.github/agents/electron-version-bump.agent.md

@@ -115,7 +115,9 @@ grep -r '"electron":' --include='package.json' -l .
 
 Compare the results with the list above and include any additional files found.
 
-### Step 3: Review and apply breaking changes
+### Step 3: Review breaking changes and get approval
+
+**This step requires explicit invoker approval before proceeding to file modifications.**
 
 Fetch the Electron breaking changes documentation. Use the raw URL to avoid GitHub rate limiting:
 
@@ -144,10 +146,7 @@ grep -r "require(\"electron\")" --include='*.ts' --include='*.js' -l .
 For each breaking change listed in the Electron docs for the new major version:
 
 1. **Identify** whether the breaking change affects any API used in this codebase.
-2. **If affected**, apply the necessary code fix:
-   - Search the codebase for all usages of the affected API.
-   - Update the code to use the new API or pattern as prescribed by the Electron breaking changes doc.
-   - Ensure backward compatibility with the minimum supported Electron version (currently ^35.0.0) — use feature detection or version checks when the old API is removed and a polyfill is needed.
+2. **If affected**, describe the required code fix and which files need modification.
 3. **If not affected**, note it and move on.
 
 **Common breaking change categories to watch for:**
@@ -159,6 +158,24 @@ For each breaking change listed in the Electron docs for the new major version:
 - New required permissions or security policy changes
 - Deprecated APIs that are now removed
 
+#### Present findings and wait for approval
+
+After completing the analysis, present a summary table to the invoker:
+
+| Breaking change | Affected? | Proposed fix |
+| --- | --- | --- |
+| (change description) | Yes / No | (fix description or "N/A") |
+
+**STOP here and wait for the invoker's explicit go-ahead before making any file changes.** If the invoker requests modifications to the proposed approach, incorporate their feedback before proceeding.
+
+#### Apply breaking change fixes (after approval)
+
+Once approved, for each affected breaking change:
+
+- Search the codebase for all usages of the affected API.
+- Update the code to use the new API or pattern as prescribed by the Electron breaking changes doc.
+- Ensure backward compatibility with the minimum supported Electron version documented in docs/learning/SupportedPlatforms.md — use feature detection or version checks when the old API is removed and a polyfill is needed.
+
 If a breaking change requires a non-trivial migration (e.g., architectural changes), document the issue in the report. If triggered from a GitHub issue, add a comment to the issue describing the blocker and wait for guidance. Otherwise, ask the invoker before proceeding with the fix.
 
 ### Step 3.5: Update `@itwin/electron-authorization` if needed
@@ -290,10 +307,13 @@ gh pr create \
   --head electron-<NEW_MAJOR> \
   --title "Add support for Electron <NEW_MAJOR>" \
   --body "$(cat <<'EOF'
-Adds support for Electron <NEW_MAJOR>.
-
 ### Breaking changes review
-<Include the breaking changes assessment here — list each change with "affected" / "not affected" status>
+
+<Include the breaking changes assessment table from Step 3 here>
+
+### Notes
+
+<Include any relevant notes, e.g. unmet peer dependencies>
 
 See [Electron <NEW_MAJOR> release blog](https://www.electronjs.org/blog/electron-<NEW_MAJOR>-0) for details.
 EOF

.github/hooks/itwinjs-core-agent-hooks.json

@@ -0,0 +1,21 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "type": "command",
+        "bash": "node .github/hooks/scripts/itwinjs-core-pre-tool-use.mjs",
+        "cwd": ".",
+        "timeoutSec": 30
+      }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "bash": "node .github/hooks/scripts/itwinjs-core-post-tool-use.mjs",
+        "cwd": ".",
+        "timeoutSec": 10
+      }
+    ]
+  }
+}

.github/hooks/scripts/itwinjs-core-hook-utils.mjs

@@ -0,0 +1,102 @@
+export async function readHookInput() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+
+  const input = Buffer.concat(chunks).toString("utf8").trim();
+  if (!input) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(input);
+  } catch {
+    return {};
+  }
+}
+
+export function parseToolArgs(toolArgs) {
+  if (!toolArgs) {
+    return {};
+  }
+
+  if (typeof toolArgs === "object") {
+    return toolArgs;
+  }
+
+  if (typeof toolArgs === "string") {
+    try {
+      return JSON.parse(toolArgs);
+    } catch {
+      return { raw: toolArgs };
+    }
+  }
+
+  return {};
+}
+
+export function getBashCommand(input) {
+  const args = parseToolArgs(input.toolArgs);
+  return typeof args.command === "string" ? args.command : "";
+}
+
+export function isGitCommitCommand(command) {
+  return /\bgit\s+(?:-[^\s]+\s+)*commit\b/.test(command);
+}
+
+export function getChangedPathText(input) {
+  const args = parseToolArgs(input.toolArgs);
+  const directPath = args.file_path ?? args.path ?? "";
+  const summary = getPathSummary(args);
+
+  try {
+    const summaryText = Object.keys(summary).length > 0 ? JSON.stringify(summary) : "";
+    return summaryText ? `${directPath}\n${summaryText}` : `${directPath}\n`;
+  } catch {
+    return `${directPath}\n`;
+  }
+}
+
+export function getChangedPaths(input) {
+  const args = parseToolArgs(input.toolArgs);
+  const paths = [];
+  for (const value of [args.file_path, args.path, args.old_path, args.new_path, args.paths, args.files]) {
+    if (typeof value === "string" && value.length > 0) {
+      paths.push(value);
+    } else if (Array.isArray(value)) {
+      paths.push(...value.filter((entry) => typeof entry === "string" && entry.length > 0));
+    }
+  }
+
+  return paths;
+}
+
+export function isPackageJsonPath(path) {
+  return String(path).split(/[\\/]/).pop() === "package.json";
+}
+
+export function isWriteLikeTool(toolName) {
+  return /^(edit|create|write|apply_patch)$/i.test(String(toolName ?? ""));
+}
+
+export function compactJson(value) {
+  return `${JSON.stringify(value)}\n`;
+}
+
+function getPathSummary(args) {
+  const summary = {};
+  for (const key of ["file_path", "path", "old_path", "new_path", "paths", "files"]) {
+    const value = args?.[key];
+    if (typeof value === "string" && value.length > 0) {
+      summary[key] = value;
+    } else if (Array.isArray(value)) {
+      const paths = value.filter((entry) => typeof entry === "string" && entry.length > 0);
+      if (paths.length > 0) {
+        summary[key] = paths;
+      }
+    }
+  }
+
+  return summary;
+}

.github/hooks/scripts/itwinjs-core-post-tool-use.mjs

@@ -0,0 +1,40 @@
+import {
+  getBashCommand,
+  getChangedPaths,
+  getChangedPathText,
+  isGitCommitCommand,
+  isPackageJsonPath,
+  isWriteLikeTool,
+  readHookInput,
+} from "./itwinjs-core-hook-utils.mjs";
+
+const input = await readHookInput();
+const messages = [];
+const isWriteLike = isWriteLikeTool(input.toolName);
+
+if (isWriteLike) {
+  const changedPaths = getChangedPaths(input);
+
+  if (changedPaths.some(isPackageJsonPath)) {
+    messages.push("[itwinjs] package.json changed - run rush update to sync pnpm-lock.yaml before committing.");
+  }
+
+  if (changedPaths.some((path) => path.includes("tsconfig")) || /tsconfig/i.test(getChangedPathText(input))) {
+    messages.push(
+      "[itwinjs] tsconfig changed - clean and rebuild to avoid stale lib/ artifacts: from the affected package directory run rushx clean && rushx build, or from the repo root use rush clean && rush build.",
+    );
+  }
+}
+
+if (String(input.toolName ?? "").toLowerCase() === "bash") {
+  const command = getBashCommand(input);
+  if (isGitCommitCommand(command)) {
+    messages.push(
+      "[itwinjs] Commit checklist: (1) any .ts files staged? -> rush lint from the repo root, or rushx lint from the affected package; (2) any @public/@beta symbol or TSDoc comment changed? -> rush extract-api + commit .api.md; (3) package.json dep changed? -> rush update committed; (4) changed a package with dependents? -> run downstream tests.",
+    );
+  }
+}
+
+if (messages.length > 0) {
+  process.stderr.write(`${messages.join("\n")}\n`);
+}

.github/hooks/scripts/itwinjs-core-pre-tool-use.mjs

@@ -0,0 +1,44 @@
+import { execFile } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compactJson, getBashCommand, isGitCommitCommand, readHookInput } from "./itwinjs-core-hook-utils.mjs";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const rushLauncherPath = resolve(repoRoot, "common/scripts/install-run-rush.js");
+
+function runRushChangeVerify() {
+  return new Promise((resolve, reject) => {
+    execFile(process.execPath, [rushLauncherPath, "change", "--verify"], { cwd: repoRoot, timeout: 30_000 }, (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error(stderr || stdout || error.message));
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+const input = await readHookInput();
+
+if (String(input.toolName ?? "").toLowerCase() !== "bash") {
+  process.exit(0);
+}
+
+const command = getBashCommand(input);
+if (!isGitCommitCommand(command)) {
+  process.exit(0);
+}
+
+try {
+  await runRushChangeVerify();
+  process.exit(0);
+} catch (error) {
+  process.stdout.write(
+    compactJson({
+      permissionDecision: "deny",
+      permissionDecisionReason: `rush change --verify failed before git commit: ${
+        error instanceof Error ? error.message.trim() : String(error)
+      }`,
+    }),
+  );
+}

.gitignore

@@ -60,6 +60,14 @@ CLAUDE.local.md
 .claude/settings.local.json
 .claude/*.local.md
 
+# GitHub Copilot CLI - personal/local overrides (do not commit)
+COPILOT.local.md
+**/COPILOT.local.md
+AGENTS.local.md
+**/AGENTS.local.md
+.copilot/settings.local.json
+.copilot/*.local.md
+
 common/api/summary/summary.exports.csv
 
 *.log

common/api/core-backend.api.md

@@ -694,7 +694,7 @@ export class BriefcaseManager {
     // @internal (undocumented)
     static getChangedElementsPathName(iModelId: GuidString): LocalFileName;
     // @internal
-    static getChangedInstancesDataForTxn(db: BriefcaseDb, txnId: string): InstancePatch[];
+    static getChangedInstancesDataForTxn(db: BriefcaseDb, txnId: string): AsyncGenerator<InstancePatch>;
     // @internal (undocumented)
     static getChangeSetsPath(iModelId: GuidString): LocalDirName;
     static getFileName(briefcase: BriefcaseProps): LocalFileName;
@@ -731,6 +731,8 @@ export class BriefcaseManager {
     // @internal
     static semanticRebaseSchemaFolderExists(db: BriefcaseDb, txnId: string): boolean;
     // @internal
+    static storeChangedInstancesForSemanticRebase(db: BriefcaseDb, txnId: string, instancePatches: IterableIterator<ChangeInstance>): void;
+    // @internal
     static storeSchemasForSemanticRebase<T extends LocalFileName[] | string[]>(db: BriefcaseDb, txnId: string, schemaFileNames: T): void;
 }
 
@@ -4542,6 +4544,7 @@ export class IModelJsFs {
     static readdirSync(pathname: string): string[];
     static readFileSync(pathname: string): string | Buffer;
     static readFileWithEncodingSync(pathname: string, encoding: BufferEncoding): string;
+    static readLines(pathname: string): AsyncGenerator<string>;
     static recursiveFindSync(rootDir: string, pattern: RegExp): string[];
     static recursiveMkDirSync(dirPath: string): void;
     static removeSync(pathname: string): void;
@@ -4679,15 +4682,9 @@ export interface InstanceChange {
 }
 
 // @internal
-export interface InstancePatch {
-    // (undocumented)
-    isIndirect: boolean;
+export interface InstancePatch extends Omit<ChangeInstance, "$meta"> {
     // (undocumented)
-    key: PatchInstanceKey;
-    // (undocumented)
-    op: "Inserted" | "Updated" | "Deleted";
-    // (undocumented)
-    props?: ECSqlRow;
+    $meta: Pick<ChangeMeta, "op" | "stage" | "isIndirectChange">;
 }
 
 // @beta
@@ -5170,6 +5167,7 @@ export class LocalHub {
     queryLocks(): LocksEntry[];
     // (undocumented)
     queryLockStatus(elementId: Id64String): LockStatus;
+    queryNearestCheckpoint(changesetIndex: ChangesetIndex): ChangesetIndex;
     queryPreviousCheckpoint(changesetIndex: ChangesetIndex): ChangesetIndex;
     // (undocumented)
     releaseAllLocks(arg: {
@@ -7588,6 +7586,8 @@ export class TxnManager {
     cancelTo(txnId: TxnIdString): IModelStatus;
     // @beta
     cancelToTxnAsync(txnId: TxnIdString, args?: ReverseTxnArgs): Promise<void>;
+    // @internal
+    protected _captureInstanceChanges(id: TxnIdString): void;
     deleteAllTxns(): void;
     endMultiTxnOperation(): DbResult;
     getChangeTrackingMemoryUsed(): number;

common/api/core-common.api.md

@@ -8622,7 +8622,7 @@ export function resolveNavProp(navProp: RelatedElementProps | undefined, depreca
 export function resolveNavPropId(navProp: RelatedElementProps | undefined, deprecatedNavPropId: Id64String): Id64String;
 
 // @internal (undocumented)
-export class ResponseLike implements Response {
+export class ResponseLike {
     constructor(data: any);
     // (undocumented)
     arrayBuffer(): Promise<ArrayBuffer>;