pm-csv 2026.10.26 → 2026.10.30

package/CHANGELOG.md

@@ -1,10 +1,20 @@
 # Changelog
 
-## 2026.10.26 - 2026-10-26
+## 2026.10.28 - 2026-10-28
 
 ### Fixed
 
-- Daily Release workflow is failing ([pm-csv-github-2b408bfa2d7f-195](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-github-2b408bfa2d7f-195.toon))
+- Prove packed CSV custom fields survive export and re-import ([pm-csv-packed-custom-fields](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-packed-custom-fields.toon))
+
+### Other
+
+- Use the pm SDK for runtime CSV export fields ([pm-csv-sdk-adoption-1025](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/tasks/pm-csv-sdk-adoption-1025.toon))
+
+## 2026.10.26 - 2026-10-26
+
+### Closed
+
+- Closed: Daily Release workflow is failing ([pm-csv-github-2b408bfa2d7f-195](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-github-2b408bfa2d7f-195.toon))
 
 ## 2026.10.25 - 2026-10-25
 
@@ -40,9 +50,7 @@
 
 ### Fixed
 
-- Daily Release workflow is failing ([pm-csv-github-2b408bfa2d7f-173](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-github-2b408bfa2d7f-173.toon))
 - Development README names TypeScript 5 while the manifest pins TypeScript 7 ([pm-csv-bqyu](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-bqyu.toon))
-- Harden the release merge wait against mergeStateStatus deadlock ([pm-csv-7izf](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-7izf.toon))
 - The changelog gate stamps an untagged version with the current date, so its verdict flips every midnight with no commit ([pm-csv-bv81](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-bv81.toon))
 - Keep toolchain acceptance aligned with built-in merge drivers and shipped history ([pm-csv-9y0w](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-9y0w.toon))
 - Make legacy CSV importer accept file input and native flags ([pm-csv-76cu](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-76cu.toon))
@@ -53,6 +61,11 @@
 
 - Certify pm-csv with pm CLI and SDK 2026.9.28 ([pm-csv-3044](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/chores/pm-csv-3044.toon))
 
+### Closed
+
+- Closed: Daily Release workflow is failing ([pm-csv-github-2b408bfa2d7f-173](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-github-2b408bfa2d7f-173.toon))
+- Closed: Harden the release merge wait against mergeStateStatus deadlock ([pm-csv-7izf](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-7izf.toon))
+
 ## 2026.10.12 - 2026-10-12
 
 ### Added
@@ -73,13 +86,16 @@
 
 ### Fixed
 
-- Daily Release workflow is failing ([pm-csv-github-2b408bfa2d7f-134](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-github-2b408bfa2d7f-134.toon))
 - A publish that npm accepts late is reported as failed and the GitHub Release is skipped on bun mirror lag ([pm-csv-c2a8](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-c2a8.toon))
 
 ### Other
 
 - Certify pm CLI 2026.9.23 and adopt the guarded pm-ops merge-driver launcher ([pm-csv-nqi5](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/chores/pm-csv-nqi5.toon))
 
+### Closed
+
+- Closed: Daily Release workflow is failing ([pm-csv-github-2b408bfa2d7f-134](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-github-2b408bfa2d7f-134.toon))
+
 ## 2026.9.18 - 2026-09-18
 
 ### Other
@@ -136,10 +152,10 @@
 
 ## 2026.9.1 - 2026-09-01
 
-### Fixed
+### Closed
 
-- Daily Release workflow is failing ([pm-csv-github-2b408bfa2d7f-86](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-github-2b408bfa2d7f-86.toon))
-- Pin pm-changelog 2026.8.30 before the next release ([pm-csv-vc26](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-vc26.toon))
+- Closed: Daily Release workflow is failing ([pm-csv-github-2b408bfa2d7f-86](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-github-2b408bfa2d7f-86.toon))
+- Closed: Pin pm-changelog 2026.8.30 before the next release ([pm-csv-vc26](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-vc26.toon))
 
 ## 2026.8.31 - 2026-08-31
 
@@ -153,9 +169,12 @@
 ### Fixed
 
 - A failed provenance publish silently falls back to an unattested one ([pm-csv-nb1m](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-nb1m.toon))
-- Fix joinContinuations whitespace, add action.yml to EXECUTABLE_PATHS, and skip value-flag args in isPublishCommand ([pm-csv-v9cs](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-v9cs.toon))
 - The publish-attestation gate misses a publish routed through an unquoted shell variable ([pm-csv-ab5t](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-ab5t.toon))
 
+### Closed
+
+- Closed: Fix joinContinuations whitespace, add action.yml to EXECUTABLE_PATHS, and skip value-flag args in isPublishCommand ([pm-csv-v9cs](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-v9cs.toon))
+
 ## 2026.8.28 - 2026-08-28
 
 ### Added
@@ -164,7 +183,6 @@
 
 ### Fixed
 
-- Full git history retains personal identity and redacted host-path blobs ([pm-csv-uaq1](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-uaq1.toon))
 - Changelog scripts consume bounded tracker output and erase release history ([pm-csv-zmcb](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-zmcb.toon))
 - Adopt the canonical certified complete-list reader ([pm-csv-t4cc](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-t4cc.toon))
 - Resume reader comment falsely permits empty map on list-all failure ([pm-csv-u254](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-u254.toon))
@@ -175,15 +193,16 @@
 - Dry-run upserts misreport existing keys as creates ([pm-csv-njaq](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-njaq.toon))
 - Latest published manifest fails pm 2026.8.20 strict health ([pm-csv-0aal](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-0aal.toon))
 
-### Security
-
-- The identity gate deadlocks the one remediation its own failure message prescribes ([pm-csv-om24](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-om24.toon))
-
 ### Other
 
 - Enable GitHub CodeQL code scanning ([pm-csv-pam9](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/chores/pm-csv-pam9.toon))
 - Alert on daily release failure and require merge drivers in CI ([pm-csv-76gz](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/chores/pm-csv-76gz.toon))
 
+### Closed
+
+- Closed: Full git history retains personal identity and redacted host-path blobs ([pm-csv-uaq1](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-uaq1.toon))
+- Closed: The identity gate deadlocks the one remediation its own failure message prescribes ([pm-csv-om24](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-om24.toon))
+
 ## 2026.8.16 - 2026-08-16
 
 ### Fixed
@@ -194,25 +213,31 @@
 
 ### Fixed
 
-- Converge changelog generation and verification on replace mode ([pm-csv-mal7](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-mal7.toon))
 - The release merge-wait read branch protection which the workflow token can never read ([pm-csv-7ifl](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-7ifl.toon))
 
 ### Other
 
 - Adopt the canonical docstring gate against a pm-ops release that skips installed extension artifacts ([pm-csv-hi55](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/tasks/pm-csv-hi55.toon))
 
+### Closed
+
+- Closed: Converge changelog generation and verification on replace mode ([pm-csv-mal7](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-mal7.toon))
+
 ## 2026.8.9 - 2026-08-09
 
 ### Fixed
 
-- Release workflow publishes npm before advancing git main, so a protected-branch push rejection permanently desyncs npm from git ([pm-csv-exz4](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-exz4.toon))
-- The overrun guard asserted a recovery outcome it never checked and reported update failures with no item id ([pm-csv-158c](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-158c.toon))
 - pm shell-outs silently degrade to wrong answers when stdout exceeds the spawnSync buffer ([pm-csv-02hc](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-02hc.toon))
 
 ### Other
 
 - Reconcile main to 2026.8.9 so git matches the npm version already published ([pm-csv-usmi](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/tasks/pm-csv-usmi.toon))
 
+### Closed
+
+- Closed: Release workflow publishes npm before advancing git main, so a protected-branch push rejection permanently desyncs npm from git ([pm-csv-exz4](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-exz4.toon))
+- Closed: The overrun guard asserted a recovery outcome it never checked and reported update failures with no item id ([pm-csv-158c](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-158c.toon))
+
 ## 2026.8.7 - 2026-08-07
 
 ### Other
@@ -247,45 +272,45 @@
 
 ## 2026.7.27 - 2026-07-27
 
-### Fixed
-
-- csv validate fails to register on pm-cli 2026.7.27 because it redeclares the host-owned --json global ([pm-csv-0orl](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-0orl.toon))
-
 ### Removed
 
 - Adopt pm-cli 2026.7.26 typed authoring contracts and remove the any-cast defineExtension shim ([pm-csv-28sk](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/tasks/pm-csv-28sk.toon))
 
-## 2026.7.26 - 2026-07-26
+### Closed
 
-### Fixed
+- Closed: csv validate fails to register on pm-cli 2026.7.27 because it redeclares the host-owned --json global ([pm-csv-0orl](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-0orl.toon))
 
-- Documented install command fails: pm install github.com/unbraind/pm-csv cannot resolve an entry file ([pm-csv-agf5](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-agf5.toon))
+## 2026.7.26 - 2026-07-26
 
 ### Other
 
 - Enable governance duplicate-detection advisory mode and adopt pm-cli 2026.7.25 ([pm-csv-kjqq](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/chores/pm-csv-kjqq.toon))
 
-## 2026.7.25 - 2026-07-25
+### Closed
 
-### Fixed
+- Closed: Documented install command fails: pm install github.com/unbraind/pm-csv cannot resolve an entry file ([pm-csv-agf5](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-agf5.toon))
 
-- pm item reads are capped at Node's 1 MiB spawnSync default, so a mature tracker fails with no diagnosis ([pm-csv-m13h](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-m13h.toon))
+## 2026.7.25 - 2026-07-25
 
 ### Other
 
 - Adopt --respect-item-release in changelog scripts and close the shipped-but-stale export terminator tracker ([pm-csv-qnax](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/chores/pm-csv-qnax.toon))
 - Redact local host paths (/home/<user\>) from tracker item history ([pm-csv-tl5j](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/chores/pm-csv-tl5j.toon))
 
-## 2026.7.23 - 2026-07-23
+### Closed
 
-### Fixed
+- Closed: pm item reads are capped at Node's 1 MiB spawnSync default, so a mature tracker fails with no diagnosis ([pm-csv-m13h](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-m13h.toon))
 
-- Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs ([pm-csv-9c2s](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-9c2s.toon))
+## 2026.7.23 - 2026-07-23
 
 ### Other
 
 - Adopt pm field-aware merge driver for multi-agent branch-merge safety ([pm-csv-3lxi](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/chores/pm-csv-3lxi.toon))
 
+### Closed
+
+- Closed: Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs ([pm-csv-9c2s](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-9c2s.toon))
+
 ## 2026.7.19-1 - 2026-07-19
 
 ### Added
@@ -298,14 +323,14 @@
 
 ## 2026.7.19 - 2026-07-19
 
-### Fixed
-
-- Fix --no-header: host rejects bare --no- flag as negation of missing --header ([pm-csv-ik4l](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-ik4l.toon))
-
 ### Other
 
 - Harden release bun-verify so registry-mirror lag cannot block the GitHub release ([pm-csv-m7i9](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/chores/pm-csv-m7i9.toon))
 
+### Closed
+
+- Closed: Fix --no-header: host rejects bare --no- flag as negation of missing --header ([pm-csv-ik4l](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-ik4l.toon))
+
 ## 2026.7.11 - 2026-07-11
 
 ### Added
@@ -407,14 +432,17 @@
 
 ### Fixed
 
-- csv export drops body (no --include-body) and uses nonexistent due_date/milestone create flags ([pm-csv-l4vy](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-l4vy.toon))
-- csv import/export return error object instead of throwing (exit 0 on failure) ([pm-csv-e9v4](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-e9v4.toon))
 - csv import --dry-run silently ignored (still writes) ([pm-csv-zw3a](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-zw3a.toon))
 
 ### Other
 
 - Production-readiness audit 2026-05-28 ([pm-csv-7jbc](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/tasks/pm-csv-7jbc.toon))
 
+### Closed
+
+- Closed: csv export drops body (no --include-body) and uses nonexistent due_date/milestone create flags ([pm-csv-l4vy](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-l4vy.toon))
+- Closed: csv import/export return error object instead of throwing (exit 0 on failure) ([pm-csv-e9v4](https://github.com/unbraind/pm-csv/blob/main/.agents/pm/issues/pm-csv-e9v4.toon))
+
 ## 2026.5.28 - 2026-05-28
 
 ### Added

package/README.md

@@ -42,11 +42,32 @@ tracker without a Git repository. None of these commands requires Git.
 | `pm csv import <file>` | Import a required CSV file; `--dry-run` previews without writes. |
 | `pm csv-import import <file>` | Same required file, flags, implementation and results as `csv import`. |
 | `pm csv validate <file>` | Validate a CSV file without writes. |
+| `pm csv admit <file>` | Stream bounded initial/full validation, counts, widths and mutation upper bounds without writes. |
 | `pm csv export` / `pm csv-export export` | Export tracker items as CSV. |
 | `pm csv schema describe <file>` | Propose a reusable versioned table schema with `--output schema.json`. |
 | `pm csv schema preview <file> --schema schema.json` | Refuse changed dialect, columns, domains or target contracts without writes. |
 | `pm csv schema import <file> --schema schema.json` | Negotiate before importing through the existing mutation core; `--dry-run` is read-only. |
 
+### Bounded import admission
+
+```sh
+pm csv admit large.csv --initial-rows 1000 --json
+pm csv admit large.csv --json
+pm csv import reviewed.csv --atomic --admission --json
+```
+
+Full admission reports exact row counts, column widths, mutation upper bounds
+and explicit resource limits. Initial observations report prefix counts and never
+authorize apply. A million-row regression runs below a fixed 128 MiB heap cap;
+atomic application separately requires at most 1,000 rows and 8 MiB. The opt-in
+import guard finishes full validation and binds the captured source bytes before
+any mutation, so an invalid final row refuses the entire admitted import.
+
+The typed SDK, limit/refusal tables and an example are in
+[bounded import admission](docs/import-admission.md). All admission commands work
+without git. SDK transaction coordination does not isolate ordinary SDK/CLI
+writers; the remaining target read/write window is documented there.
+
 ### Versioned table schema negotiation
 
 Save a reviewed mapping once and reuse it without silently reinterpreting a
@@ -84,9 +105,24 @@ pm csv import legacy.csv --encoding latin1  # non-UTF-8 source
 pm csv import sprint12.csv --source 'jira-export-2026-06'
 pm csv import vendor.csv --strict       # fail before writing on bad row data
 pm csv import items.csv --dry-run
-pm csv import tasks.csv --atomic   # writer-locked, crash-recoverable import
+pm csv import tasks.csv --atomic   # SDK-coordinated, crash-recoverable import
 ```
 
+**Column ownership on keyed updates:** an absent header means “do not touch”.
+Empty cells also leave existing values alone. A nonempty cell sets a supported
+field; `none` or `null` (case-insensitive) explicitly clears a supported nullable scope
+field: `parent`, `assignee`, `sprint`, `release` or `blocked_by`. Tags are additive;
+`blocked_by` adds a blocker without deleting other dependency edges. Custom fields
+are export-only and remain unchanged on import. Thus a title-only `--key title`
+reimport preserves status, assignment, planning fields, body, links and custom data.
+New items explicitly suppress implicit focus parents and planning defaults.
+Spreadsheet edit sessions have their own documented explicit-clear contract.
+Replay compares command values through SDK field normalization: local parents such
+as `abcd`, `#ABCD` and `pm-abcd` resolve using the tracker prefix; provider locators
+retain their native spelling. Assignment/planning whitespace and clear aliases
+follow native command semantics. Stored edit-session values instead use SDK document
+canonicalization, preserving literal strings such as `none`.
+
 **Flags**
 
 | Flag | Type | Default | Description |
@@ -102,7 +138,8 @@ pm csv import tasks.csv --atomic   # writer-locked, crash-recoverable import
 | `--priority <n>` | integer | — | Import **only** rows whose integer priority equals this value |
 | `--strict` | boolean | false | Abort before writing if validation finds missing titles, unknown statuses, invalid/out-of-range priorities, or duplicate mapped columns |
 | `--dry-run` | boolean | false | Preview what would be imported without writing any data |
-| `--atomic` | boolean | false | Use one writer-locked, crash-recoverable transaction. On failure, attempt best-effort create compensation; pre-existing updates restore captured prior values unless a conflict prevents safe compensation. Inspect and reconcile any marked orphan before retrying. Incompatible with `--stream` |
+| `--admission` | boolean | false | Finish bounded full validation and enforce atomic row/byte budgets before application; requires `--atomic` |
+| `--atomic` | boolean | false | Use one SDK-coordinated, crash-recoverable transaction. On failure, attempt best-effort create compensation; pre-existing updates restore captured prior values unless a conflict prevents safe compensation. Inspect and reconcile any marked orphan before retrying. Incompatible with `--stream` |
 
 #### Strict import gate
 
@@ -437,6 +474,15 @@ plus complete CSV export in fresh npm/npx and Bun/bunx projects on the pinned
 development host, and in npm/npx on the declared minimum host. It is mandatory
 inside `npm run release:check`.
 
+Every scenario seeds custom string, number, boolean, ISO date string, list and
+empty-string values through its installed host SDK. Automatic `--all-fields`
+discovery and explicit custom-column selection must export each value exactly,
+including quoted multiline text, zero, false and empty lists. The packed
+package's CSV parser then decodes the export for SDK import into a fresh
+non-git tracker; SDK reads compare every custom value with the source tracker.
+This SDK adapter roundtrip does not certify custom-column support in the legacy
+`pm csv import` command, whose supported columns are listed above.
+
 ```bash
 npm install
 npm run build   # runs tsc → dist/
@@ -524,3 +570,50 @@ keys make unchanged retries idempotent. The compact TOON/JSON receipt reports
 counts; artifacts include SHA-256 checksums. See the [protocol and worked
 example](docs/row-lineage.md) for the typed SDK, mapping revisions, refusals,
 privacy policy and recovery behavior.
+
+## Cross-table reference joins
+
+Resolve explicit external-key parent and dependency columns across selected tables
+in one preview, then apply the reviewed source digests through SDK transactions.
+
+```sh
+pm csv join preview joins.json --output reviewed.json --json
+pm csv join apply reviewed.json --json
+```
+
+Duplicate or unresolved keys include cell coordinates and block import. See the
+[three-table example, typed SDK API, bounds and recovery contract](docs/join-plans.md).
+These create-only plans work without git. Retain the reviewed artifact for crash
+recovery. Ordinary failures compensate unchanged owned creates and retain native
+delete history; interrupted cleanup revalidates every target before continuing.
+After compensation, preview fresh identities. Configured type/field lookups never
+accept inherited object properties, while prototype-looking external keys remain
+literal data. Foreign records and peer edits are preserved.
+
+Saved join and checkout IDs must use distinct canonical native spellings under
+the reviewed SDK prefix. All IDs validate before target leases or writes;
+`abcd` and `review-abcd` cannot identify two rows with prefix `review`, even in
+a correctly rehashed artifact. Preview a fresh plan after `csv_join_invalid`.
+
+Join journal identity covers the full reviewed plan, independent of current
+foreign-row eligibility. Retry resumes pending compensation under its recorded
+key and step list before new work. Historical subset journals remain recoverable;
+convergent spreadsheet values cannot bypass their cleanup. Atomic CSV retry with
+changed filters or mappings refuses when it would shrink or change an existing
+journal's row domain: resume using the original options to finish recovery first.
+
+Join planning captures one settings/schema snapshot. Create type and status
+defaults are resolved from that snapshot before writes; every mutation batch
+rechecks its digest inside SDK writer coordination. A settings change between
+rows returns `csv_join_settings_changed` and compensates unchanged owned creates.
+Recovery uses one separately guarded current-policy snapshot for cleanup. Peer
+edits or further policy changes can require journal reconciliation. Inputs and
+the tracker root are captured before asynchronous SDK reads, so caller edits or
+working-directory changes cannot redirect an in-flight plan.
+
+CSV mutations use explicit source-owned scope: missing or empty create parents
+are unset through the SDK, so session focus cannot add links. Empty supported
+scope cells preserve legacy keyed-import state; spreadsheet patches preserve
+unselected fields. Join replay refuses unreviewed stored scope. Public join
+failures consistently use `JoinRefusal`, with lower-level `sourceCode` and remedy
+retained. See [scope and refusal contracts](docs/join-plans.md#explicit-scope-and-refusal-boundaries).

package/dist/admission.d.ts

@@ -0,0 +1,93 @@
+import { PmCliError } from "@unbrained/pm-cli/sdk";
+import type { ExtensionApi } from "@unbrained/pm-cli/sdk/authoring";
+import type { PmSettings } from "@unbrained/pm-cli/sdk";
+import type { ImportRowFilter } from "./index.ts";
+/** Hard allocation and materialization ceilings; callers can only lower them. Units are UTF-16 code units unless named bytes. */
+export declare const ADMISSION_LIMITS: Readonly<Record<"maxFieldCodeUnits" | "maxRecordCodeUnits" | "maxColumns" | "maxAtomicBytes" | "maxAtomicRows" | "maxSourceBytes", number>>;
+/** One strict SDK/CLI boundary; initial scans never authorize apply. */
+export interface AdmissionOptions {
+    mode?: "initial" | "full";
+    initialRows?: number;
+    delimiter?: string;
+    encoding?: "utf-8" | "utf8" | "utf16le" | "latin1";
+    skipHeaders?: boolean;
+    fieldMap?: Record<string, string>;
+    autoMap?: boolean;
+    filter?: ImportRowFilter;
+    maxFieldCodeUnits?: number;
+    maxRecordCodeUnits?: number;
+    maxColumns?: number;
+    maxAtomicBytes?: number;
+    maxAtomicRows?: number;
+    maxSourceBytes?: number;
+}
+/** Compact source-free receipt. Mutation work is a row-operation upper bound, never an exact create/update count or heap prediction. */
+export interface AdmissionReceipt {
+    version: 1;
+    mode: "initial" | "full";
+    ok: boolean;
+    complete: boolean;
+    admitted: boolean;
+    digest?: string;
+    rows: {
+        value: number;
+        kind: "exact" | "lower_bound";
+    };
+    invalidRows: number;
+    issues: {
+        row: number;
+        code: "row_width" | "row_invalid";
+    }[];
+    fieldWidths: number[];
+    mutationWork: {
+        value: number;
+        kind: "upper_bound";
+    };
+    sourceBytes: number;
+    limits: typeof ADMISSION_LIMITS;
+    remedy?: string;
+}
+/** Stable refusal families; no source cells, source paths or low-level IO text is exposed. */
+export type AdmissionRefusalCode = "csv_admission_options" | "csv_admission_io" | "csv_admission_limit" | "csv_admission_invalid" | "csv_admission_incomplete" | "csv_admission_source_changed" | "csv_admission_settings_changed" | "csv_admission_target_changed" | "csv_admission_sdk";
+/** Expected semantic failure with a concrete retry action. */
+export declare class AdmissionRefusal extends PmCliError {
+    /** Stable category for an automated retry decision. */
+    readonly code: AdmissionRefusalCode;
+    /** Concrete repair action, excluding source content. */
+    readonly remedy: string;
+    constructor(code: AdmissionRefusalCode, remedy: string);
+}
+/** Keep admission and its native application in one settings-refusal family. */
+export declare function admissionSettingsChanged(): AdmissionRefusal;
+/** Preserve typed admission remedies when native transaction compensation aggregates failures. */
+export declare function findAdmissionFailure(error: unknown, seen?: Set<unknown>): AdmissionRefusal | undefined;
+/** Older hosts keep read-only admission; applying needs the native semantic preview capability. */
+export declare function requireAdmissionCapability<T extends (...args: never[]) => unknown>(value: T | undefined): T;
+/** Preserve a concrete host/storage remedy when an older SDK previews installed dependency links. */
+export declare function admissionPreviewFailure(error: unknown): AdmissionRefusal;
+/** Validate options once before IO, including finite integer domains and bounded own-key mappings. */
+export declare function parseAdmissionOptions(value: AdmissionOptions): Required<AdmissionOptions>;
+/** Normalize a selected status through the same native registry as row writes, preserving source-based type filtering. */
+export declare function normalizeAdmissionFilter(filter: ImportRowFilter, settings: PmSettings): ImportRowFilter | undefined;
+/** Refuse unusable resource reports before an atomic caller allocates a row plan. */
+export declare function assertCSVAdmission(receipt: AdmissionReceipt): void;
+/** Capture bounded bytes for the existing atomic parser, refusing source drift before materialization or writes. */
+export declare function readAdmittedSource(file: string, digest: string, maxBytes?: number): Buffer;
+/** Require current native state or the latest immutable success of exactly this row. */
+export declare function admissionTargetRevision(pmRoot: string, id: string, expected?: string, appliedMarker?: string): Promise<string>;
+/** Reconcile ordered writes to one native target; later rows prove the completed prefix, including reverse compensation. */
+export declare function admissionTargetSequence(pmRoot: string, id: string, expected: string, markers: readonly string[]): Promise<{
+    revision: string;
+    completed: number;
+}>;
+/** Check every emitted count and width before returning success, also useful to consumers validating receipts. */
+export declare function assertAdmissionNumbers(receipt: AdmissionReceipt): void;
+/** Read-only admission against one SDK settings revision. Source size never determines retained row count. */
+export declare function admitCSV(pmRoot: string, file: string, options?: AdmissionOptions, diagnostics?: AdmissionDiagnostics): Promise<AdmissionReceipt>;
+/** Trusted observer for deterministic concurrency diagnostics, outside the untrusted options schema. */
+export interface AdmissionDiagnostics {
+    onBoundary?: (phase: "opened" | "read" | "validated") => void | Promise<void>;
+}
+/** Register one host-rendered compact TOON/JSON command; no source values or artifacts are emitted. */
+export declare function registerAdmissionCommand(api: ExtensionApi): void;
+//# sourceMappingURL=admission.d.ts.map

package/dist/admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.d.ts","sourceRoot":"","sources":["../admission.ts"],"names":[],"mappings":"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"}