Update library examples and verify scored rename parsing

Author: mchwang

README.md

@@ -20,7 +20,7 @@ Tests create disposable local repositories. They do not invoke agents, access Gi
 
 - `core/plan.ts`: schema validation; YAML/JSON import; projected file-state and dependency checks; literal command parsing; individual suggestion validation and application.
 - `git/history.ts`: reads an immutable base-to-head commit range and file blobs. Uses argv, disables external diff/textconv helpers, hooks, and replacement objects.
-- `core/linking.ts`: replays line changes using an explicit `Map<commitSha, planItemId>` supplied by the caller. Trailers never establish ownership. Foreign work is Unplanned; overlapping item edits are Ambiguous; undeclared edits stay on their owner's row as out of scope.
+- `core/linking.ts`: replays line changes using an explicit `Map<commitSha, planItemId | null>` supplied by the caller. Trailers never establish ownership. Foreign work is Unplanned; overlapping item edits are Ambiguous; undeclared edits stay on their owner's row as out of scope.
 - `core/approvals.ts`: approval snapshots, dependency staleness, assignments, and accept-as-is choices keyed by content and duplicate occurrence/count.
 
 Example from TypeScript (Node can load these source modules):
@@ -31,23 +31,25 @@ import { readHistory } from './git/history.ts';
 import { linkHistory } from './core/linking.ts';
 
 const { plan, warnings } = importPlan(planText, 'yaml', {
-  baseFiles: pathsAtBaseCommit, // Include symlink and submodule entries, never their targets.
+  identity: storedPlanIdentity, // Stable repositoryId, taskId, and planId from storage.
+  baseEntries: entriesAtBaseCommit, // Typed file/gitlink entries; symlinks include target text.
+  pathKey: checkoutPathKey, // Actual checkout case/Unicode identity; fail if unknown.
   allowedCommands: [['npm', 'test']],
   issue: 412,
 }, nextRevision);
 const history = readHistory(repoPath, baseCommit, headCommit);
-const segments = linkHistory(plan, history, trustedCommitLedger);
+const segments = linkHistory(plan, history, trustedCommitLedger, checkoutPathKey);
 ```
 
-Inputs such as `planText` and the ledger must come from the caller. The future `runner/store` owns the database and ledger; this library does not infer them from commit messages. Before saving a suggested edit, the store must compare-and-swap the plan revision in one transaction. The pure `applySuggestion` function validates a copy but cannot lock storage.
+Inputs such as `planText` and the ledger must come from the caller. The future `runner/store` owns the database and ledger; this library does not infer them from commit messages. Before saving a suggested edit, the store must load its captured identity/revision binding by opaque suggestion ID, reject canceled or consumed IDs, and compare-and-swap the plan revision plus consume/invalidate old suggestions in one transaction. The pure `applySuggestion` function requires that trusted binding and validates a copy, but cannot lock storage or prevent replay by itself. Applying one card stales its siblings; refresh and review regenerated cards before the next Apply. Approvals and choices likewise require the stored plan identity.
 
 ## Current limits and safety
 
 - History must be linear and descend from the requested base. Merge histories are rejected with a rebase instruction; repositories using object alternates or symlinked object storage are rejected (storage inspection is limited to 100,000 entries). Reads are bounded to 500 commits, 32 MiB per Git response, 64 MiB of unique blob bytes across the history (callers may lower `maxBlobBytes`), 8 MiB of cumulative diff output, 20,000 cumulative file records (including the final diff), and a 2-second budget per line diff; oversized work fails explicitly.
 - The caller selects and trusts the repository and its Git administrative directory. Normal Git discovery, linked-worktree gitfiles, and symlinked gitdirs are supported; object-storage links and alternates inside that selected gitdir are rejected. This adapter is not a filesystem-containment boundary for untrusted repository roots.
 - Object storage must remain unchanged during a read; these library checks do not isolate a concurrently hostile filesystem.
 - Ownership uses line diffs, not semantic inference. Within one replacement block, new lines inherit all affected owners conservatively. Function context comes from Git hunk headers, not an AST.
-- The importer requires an accurate base-file list. It rejects path traversal, Git metadata paths, and traversal through a listed file/symlink/submodule. Runtime symlink and write-scope enforcement belong to the future container/runner; plan validation alone is not a sandbox.
+- The importer requires accurate typed base entries, stable plan identity, a selected issue, and a trusted checkout path-identity function. It rejects path traversal, Git metadata paths, and traversal through a listed file/symlink/submodule. Runtime symlink and write-scope enforcement belong to the future container/runner; plan validation alone is not a sandbox.
 - Allowed commands restrict accidents, not hostile programs or changed scripts. Parsing returns argv and never executes it. An unlisted valid command is a warning and must not run until allowed.
 - No code here claims container isolation, vendor-only network access, credential protection, or safe dependency installation. Those controls must be implemented before running agents.
 

docs/implementation/build-step-1.md

@@ -90,3 +90,7 @@ Validation began with 60 passing tests. The added v1 regressions reproduced 18 f
 ### Explicit remaining work
 
 Issue #6 remains open for runner/store integration: obtain typed base entries and actual filesystem identity from a trusted checkout; audit actual occupancy, new symlinks/conversions, link targets and target mutations after execution; provide persistent request IDs, cancellation, replay prevention and concurrent CAS; enforce prompt budgets/profiles, output limits, container mounts, and process termination. The library only checks declared/projected state and trusted supplied context. In particular an edit may repair an unsafe existing link, but only the future runtime audit can validate its new target and accepted filesystem state. No application, runtime safety boundary, or concurrent store has been added here. Issues #2 and #3 remain the next approved build steps.
+
+## Merged-contract review round 1
+
+Updated README import/linking examples to supply the new required context. Declined the scored-rename report: the raw-diff regex captures only `([A-Z])` and consumes the score separately with `\d*`, so the existing branch receives `R`, not `R100`. A focused real-Git test observed a scored rename followed by an added-file record and loaded both correctly before any parser change. Retained that regression. A separate locally discovered C1-control regression failed first, then passed after using the complete Unicode control category for commands/paths.

test/history.test.ts

@@ -257,3 +257,16 @@ it('records typed object identities on real mode-change cards', () => {
   expect(metadata.oldObject.oid).toBe(metadata.newObject.oid);
   expect(metadata.oldMode).toBe('100644'); expect(metadata.newMode).toBe('100755');
 });
+
+it('parses scored renames and consumes both paths before the next raw record', () => {
+  const initial = Array.from({ length: 100 }, (_, i) => `line ${i}\n`).join('');
+  const f = fixture({ 'a.txt': initial });
+  renameSync(join(f.dir, 'a.txt'), join(f.dir, 'b.txt'));
+  f.write('b.txt', initial.replace('line 50\n', 'changed 50\n'));
+  f.write('z.txt', 'another record\n'); const head = f.commit('P1');
+  const raw = f.git('diff', '--raw', '-z', '-M', f.base, head);
+  expect(raw).toMatch(/ R\d+\0a\.txt\0b\.txt\0/u);
+  const history = readHistory(f.dir, f.base);
+  expect(history.final.some(d => d.oldPath === 'a.txt' && d.newPath === 'b.txt')).toBe(true);
+  expect(history.final.some(d => d.oldPath === null && d.newPath === 'z.txt')).toBe(true);
+});