@ouronet/ouronet-core 4.3.7 → 4.4.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to `@ouronet/ouronet-core`.
 
 This package is the historical continuation of `@ouronet/ouronet-core` v0.x–v3.3.8. v4.0.0 split it into a two-package npm workspace under `StoaChain/stoa-js` — chain-generic infrastructure moved out into [`@stoachain/stoa-core`](https://www.npmjs.com/package/@stoachain/stoa-core), this package retained the Ouronet-specific business logic. The `4.0.0` heading below is the first release after the split.
 
+## 4.4.0 — 2026-07-22
+
+**MINOR — the codex writer is held at `"1.2"` while the reader keeps accepting `"1.2"` and `"1.3"`.**
+
+### Read this before upgrading from 4.3.6 or 4.3.7
+
+Those two releases were a mistake, and this one corrects it. They were built from the source repo's `main`, which carried codex-**1.3** writer work that had never been released, and they were published under version numbers the old `@stoachain/ouronet-core` had already used. So `@stoachain/ouronet-core@4.3.6` and `@ouronet/ouronet-core@4.3.6` are the same number with **different behaviour**: the first writes codex `"1.2"`, the second writes `"1.3"`.
+
+That matters because the format bump is governed by reader-before-writer discipline — the reader is widened everywhere first, and only then does the writer advance. Shipping a 1.3 writer skipped that step: an app on 4.3.6/4.3.7 produces backups that any app still on a 1.2-only reader cannot open, including `@ancientpantheon/codex`, which deliberately gates on 1.2 until its D-phase is ready.
+
+### What 4.4.0 does
+
+- The **reader still accepts both** `"1.2"` and `"1.3"` — no narrowing, ever. Any 1.3 file already written by 4.3.6/4.3.7 remains readable.
+- The **writer stamps `"1.2"`** again, so nothing new is produced that the rest of the ecosystem cannot read.
+- Nothing is lost by this. ouronet's `PlaintextCodex` has no foreign-key source field, so the writer never emitted the 1.3-only `foreignKeys` block — its 1.2 and 1.3 output differed only in the version string.
+- It is a MINOR, not a patch, because the reader's widened acceptance is genuinely new surface relative to the last honest release.
+
+`@ouronet/ouronet-core@4.3.6` and `@4.3.7` are deprecated on npm and point here.
+
+### Advancing the writer later
+
+Confirm every consumer resolves a 1.3-capable reader (4.3.6+ under this scope) and that `@ancientpantheon/codex` no longer rejects 1.3, then flip the single `version` literal in `src/codex/codec.ts` and ship it as another MINOR. `tests/v4-3-x-codec-1-3-writer.test.ts` documents that procedure and holds the invariant either way — its round-trip cases are version-agnostic on purpose.
+
+**787 specs pass.**
+
 ## 4.3.7 — 2026-07-22
 
 **PATCH — chain-peer realignment, no code change.**

package/README.md

@@ -5,17 +5,26 @@ Ouronet protocol business logic on top of [`@stoachain/stoa-core`](https://www.n
 Chain-generic infrastructure (signing, wallet, crypto, network failover, gas, guard, errors, observability, dalos, reads, pact-format helpers) lives in the sibling [`@stoachain/stoa-core`](https://www.npmjs.com/package/@stoachain/stoa-core) package — install both, or just this one if you only need the Ouronet-specific surface.
 
 > **Renamed.** This package was published as `@stoachain/ouronet-core` through 4.3.5. The
-> code, version line, and release history continue unbroken under the `@ouronet` scope —
+> version line and release history continue under the `@ouronet` scope —
 > the published name now matches the organisation that owns it. The old name is deprecated
-> on npm and points here. Migration is a rename and nothing else:
+> on npm and points here. At the import level, migration is a rename:
 >
 > ```diff
 > - import { serializeCodex } from "@stoachain/ouronet-core/codex";
 > + import { serializeCodex } from "@ouronet/ouronet-core/codex";
 > ```
+>
+> ⚠️ **But 4.3.6/4.3.7 here are NOT byte-identical to `@stoachain/ouronet-core@4.3.6`.**
+> This package was built from the source repo's `main`, which carried codex-**1.3**
+> work that had never been released. The old 4.3.6 writes codex `"1.2"`; these
+> versions write `"1.3"`. If you consume the codex writer, that is a behaviour
+> change, not a rename — verify against your reader before upgrading. Resolving
+> this mislabelling is tracked as an open issue.
 
 ## Status
 
+**`4.4.0` on public npmjs** — **MINOR (codec writer held at 1.2; reader still accepts 1.2 and 1.3).** Released 2026-07-22. Corrects 4.3.6/4.3.7, which shipped an unreleased 1.3 *writer* and so produced backups that apps on a 1.2-only reader could not open. The reader is unchanged and still accepts both, so any 1.3 file already written stays readable; the writer stamps 1.2 again. Nothing is lost — this writer never emitted the 1.3-only `foreignKeys` block. Those two versions are deprecated and point here. **787 specs pass.**
+
 **`4.3.7` on public npmjs** — **PATCH (chain-peer realignment with `@stoachain/stoa-core@4.3.7` + `@stoachain/kadena-stoic-legacy@4.3.7`).** Released 2026-07-22. NO code changes in this package. The exact chain peers move 4.3.6 → 4.3.7 so consumers resolving the current chain layer get a satisfiable tree; stoa-js 4.3.7 repointed DALOS onto `@ouronet/dalos-crypto@4.0.4`. **785 specs pass.**
 
 **`4.3.6` on public npmjs** — **PATCH (atomic-triplet alignment with `@stoachain/stoa-core@4.3.6` + `@stoachain/kadena-stoic-legacy@4.3.6`).** Released 2026-06-11. NO code changes in this package; version bumped solely to maintain the atomic-triplet invariant. The v4.3.6 change (a `@stoachain/stoa-core` auto-gas-limit floor fix in `calculateAutoGasLimit`) lives entirely in `@stoachain/stoa-core`. Functionally identical to `4.3.5`. **829 specs pass.**
@@ -36,6 +45,8 @@ Chain-generic infrastructure (signing, wallet, crypto, network failover, gas, gu
 
 **`4.2.0` on public npmjs** — **MINOR (atomic with `@stoachain/stoa-core@4.2.0` + `@stoachain/kadena-stoic-legacy@4.2.0`).** Released 2026-05-09. Closes 6 audit findings: **F-ARCH-001** (Phase 1 dex god-file split — ~10 entity-oriented files + thin re-export shim), **F-ARCH-002** (Phase 2 ouro god-file split + chain/UI surgical separation — ~11 entity-oriented files + thin re-export shim), **F-ARCH-003** (Phase 3 parameterized liquidity executor — 5 thin wrappers + 1 internal `executeLiquidityOp`, LOC reduction ~600 → ~200), **F-API-002** (Phase 4 — 12 functions honor declared `Promise<T | null>` contract, return null on RPC failure instead of rethrowing), **F-API-018** (Phase 5 readonly sweep — ~50 public-type fields in `codex/types.ts` and all `*Params` interfaces), **F-TEST-006** (Phase 7 — +127 specs across 6 modules: `infoOneFunctions`, `coilFunctions`, `kpayFunctions`, `pensionFunctions`, `activateFunctions`, `guardFunctions`). NEW deliverable: [`INTEGRATION-GUIDE.md`](https://github.com/StoaChain/stoa-js/blob/main/INTEGRATION-GUIDE.md) at repo root — comprehensive cold-start consumer onboarding doc, 13 sections, full v4.0 → v4.1 → v4.2 architectural arc. 8 new `v4-2-0-*.test.ts` regression-lock files. Test count: **710 specs pass** (was ~330 in v4.1.1). Cross-reference: see [`MIGRATION-v4.2.md`](https://github.com/StoaChain/stoa-js/blob/main/MIGRATION-v4.2.md) at the monorepo root.
 
+**v4.4.0** — codec writer held at `"1.2"`; reader still accepts `"1.2"` and `"1.3"`. Released 2026-07-22. Corrects the 4.3.6/4.3.7 mispublish, which shipped an unreleased 1.3 writer under version numbers the old `@stoachain` package had already used. **787 specs pass.**
+
 **v4.3.7** — chain-peer realignment bump (exact peers on `@stoachain/stoa-core@4.3.7` + `@stoachain/kadena-stoic-legacy@4.3.7`). Released 2026-07-22. NO code changes. Required because this package pins its chain peers exactly and stoa-js now releases independently. **785 specs pass.**
 
 **v4.3.6** — atomic-triplet alignment bump (atomic with `@stoachain/stoa-core@4.3.6` + `@stoachain/kadena-stoic-legacy@4.3.6`). Released 2026-06-11. NO code changes; the v4.3.6 change (a stoa-core auto-gas-limit floor fix in `calculateAutoGasLimit`) lives in `@stoachain/stoa-core`. Functionally identical to v4.3.5. **829 specs pass.**

package/dist/codex/codec.d.ts

@@ -4,20 +4,33 @@
  * the same backup JSON (HUB's codex-import flow, CLI recovery tools,
  * etc.).
  *
- * The written format is now `CodexExportV1_3` — the `"version": "1.3"`
- * string. This was an INTENTIONAL 1.2→1.3 bump made under strict
- * reader-before-writer discipline: `deserializeCodex` was widened to
- * accept BOTH "1.2" and "1.3" (and to allow-list the optional
- * `foreignKeys` block) BEFORE this writer began stamping "1.3". That
- * ordering is what makes the bump safe — every previously downloaded
- * `OuronetCodex_*.json` (still "1.2") keeps importing, and every new
- * export ("1.3") deserializes through the same reader.
+ * `deserializeCodex` accepts BOTH "1.2" and "1.3" (and allow-lists the
+ * optional `foreignKeys` block). The writer currently stamps **"1.2"**.
  *
- * Do NOT revert the writer to "1.2" in isolation, and do NOT narrow the
- * reader back to "1.2"-only: emitting a version the reader rejects (or
- * rejecting the version the writer emits) is a funds-loss inversion — a
- * user's own fresh backup would fail to restore. Any future format change
- * must keep the reader ahead of the writer.
+ * THE INVARIANT: the reader must stay ahead of the writer. Emitting a
+ * version the reader rejects — or rejecting the version the writer emits —
+ * is a funds-loss inversion, because a user's own fresh backup would fail
+ * to restore. The reader is therefore always widened first, in a release
+ * that ships everywhere, and only then does the writer advance.
+ *
+ * Why the writer sits at "1.2" while the reader already understands "1.3":
+ * that is the mid-point of the migration, and it is deliberate. The reader
+ * half shipped; the writer half has not, because the ecosystem is not yet
+ * uniformly on a 1.3-capable reader — `@ancientpantheon/codex` still gates
+ * on 1.2. A writer that ran ahead would produce backups that the user's own
+ * other apps could not open. That is the exact inversion above, one step
+ * removed.
+ *
+ * This writer's 1.3 output was a BARE envelope — ouronet's `PlaintextCodex`
+ * has no foreign-key source field, so no `foreignKeys` block was ever
+ * emitted. The only difference between its 1.2 and 1.3 output is the
+ * version string itself, which is why holding at "1.2" costs no capability.
+ *
+ * TO ADVANCE THE WRITER TO "1.3": confirm every consumer resolves a core
+ * whose reader accepts 1.3 (that is 4.3.6+ under the @ouronet scope), and
+ * that `@ancientpantheon/codex` no longer rejects 1.3, then flip the
+ * `version` literal below and ship it as a MINOR. Do not narrow the reader
+ * at any point.
  *
  * All pure. No password handling in here — the BYTES INSIDE the JSON are
  * already encrypted at the codex-entry level (each wallet's `secret` field
@@ -27,19 +40,20 @@
 import type { CodexExportV1_2, CodexExportV1_3, PlaintextCodex } from "./types.js";
 /**
  * Build a codex-export payload from a PlaintextCodex. Stamps the current
- * `"1.3"` envelope version and `exportedAt` with the current ISO time.
+ * `"1.2"` envelope version and `exportedAt` with the current ISO time.
  * Returns the object — the caller stringifies it (so callers in a
  * memory-constrained environment can stream it out instead of holding the
  * whole string in RAM).
  *
- * The return type is the `CodexExportV1_2 | CodexExportV1_3` union so
- * consumers written against the historical 1.2 shape still type-check
- * against the widened output; the runtime value is always a 1.3 envelope.
+ * The return type is the `CodexExportV1_2 | CodexExportV1_3` union so this
+ * signature does not have to change when the writer advances to 1.3; the
+ * runtime value today is a 1.2 envelope. See the file header for why the
+ * writer trails the reader and what has to be true before it advances.
  *
- * The optional `foreignKeys` block is EMITTED only when the source codex
- * carries foreign keys. ouronet's `PlaintextCodex` has no foreign-key
- * source field today, so the practical output is a bare 1.3 envelope with
- * `foreignKeys` omitted — no mandatory empty block.
+ * The optional `foreignKeys` block belongs to the 1.3 shape and is never
+ * emitted here — ouronet's `PlaintextCodex` has no foreign-key source
+ * field — so the output carries no 1.3-only data and nothing is lost by
+ * stamping 1.2.
  *
  * Fields left out intentionally: `pureKeypairs`, `schemaVersion`,
  * `lastUpdatedAt`, `lastUpdatedDevice` — see CodexExportV1_3 JSDoc for
@@ -47,7 +61,7 @@ import type { CodexExportV1_2, CodexExportV1_3, PlaintextCodex } from "./types.j
  */
 export declare function buildCodexExport<KS, OA, PK, AB, UI>(codex: PlaintextCodex<KS, OA, PK, AB, UI>): CodexExportV1_2<KS, OA, AB, UI> | CodexExportV1_3<KS, OA, AB, UI>;
 /**
- * Stringify a PlaintextCodex into the `"1.3"` backup JSON format, the
+ * Stringify a PlaintextCodex into the `"1.2"` backup JSON format, the
  * exact output of OuronetUI's LocalStorageCodexAdapter.downloadAsJson.
  * Pretty-prints with 2-space indent because the file lands on disk and
  * a human occasionally opens it to sanity-check account addresses.
@@ -62,7 +76,7 @@ export declare function serializeCodex<KS, OA, PK, AB, UI>(codex: PlaintextCodex
  * Throws on:
  *   - invalid JSON
  *   - missing `"version"` field (malformed)
- *   - version mismatch (not `"1.2"`)
+ *   - version mismatch (neither `"1.2"` nor `"1.3"`)
  *   - shape mismatch (kadenaWallets, ouronetWallets, addressBook not arrays; uiSettings not an object)
  *
  * The version check exists to fail-fast rather than silently mis-decoding

package/dist/codex/codec.js

@@ -4,20 +4,33 @@
  * the same backup JSON (HUB's codex-import flow, CLI recovery tools,
  * etc.).
  *
- * The written format is now `CodexExportV1_3` — the `"version": "1.3"`
- * string. This was an INTENTIONAL 1.2→1.3 bump made under strict
- * reader-before-writer discipline: `deserializeCodex` was widened to
- * accept BOTH "1.2" and "1.3" (and to allow-list the optional
- * `foreignKeys` block) BEFORE this writer began stamping "1.3". That
- * ordering is what makes the bump safe — every previously downloaded
- * `OuronetCodex_*.json` (still "1.2") keeps importing, and every new
- * export ("1.3") deserializes through the same reader.
+ * `deserializeCodex` accepts BOTH "1.2" and "1.3" (and allow-lists the
+ * optional `foreignKeys` block). The writer currently stamps **"1.2"**.
  *
- * Do NOT revert the writer to "1.2" in isolation, and do NOT narrow the
- * reader back to "1.2"-only: emitting a version the reader rejects (or
- * rejecting the version the writer emits) is a funds-loss inversion — a
- * user's own fresh backup would fail to restore. Any future format change
- * must keep the reader ahead of the writer.
+ * THE INVARIANT: the reader must stay ahead of the writer. Emitting a
+ * version the reader rejects — or rejecting the version the writer emits —
+ * is a funds-loss inversion, because a user's own fresh backup would fail
+ * to restore. The reader is therefore always widened first, in a release
+ * that ships everywhere, and only then does the writer advance.
+ *
+ * Why the writer sits at "1.2" while the reader already understands "1.3":
+ * that is the mid-point of the migration, and it is deliberate. The reader
+ * half shipped; the writer half has not, because the ecosystem is not yet
+ * uniformly on a 1.3-capable reader — `@ancientpantheon/codex` still gates
+ * on 1.2. A writer that ran ahead would produce backups that the user's own
+ * other apps could not open. That is the exact inversion above, one step
+ * removed.
+ *
+ * This writer's 1.3 output was a BARE envelope — ouronet's `PlaintextCodex`
+ * has no foreign-key source field, so no `foreignKeys` block was ever
+ * emitted. The only difference between its 1.2 and 1.3 output is the
+ * version string itself, which is why holding at "1.2" costs no capability.
+ *
+ * TO ADVANCE THE WRITER TO "1.3": confirm every consumer resolves a core
+ * whose reader accepts 1.3 (that is 4.3.6+ under the @ouronet scope), and
+ * that `@ancientpantheon/codex` no longer rejects 1.3, then flip the
+ * `version` literal below and ship it as a MINOR. Do not narrow the reader
+ * at any point.
  *
  * All pure. No password handling in here — the BYTES INSIDE the JSON are
  * already encrypted at the codex-entry level (each wallet's `secret` field
@@ -27,19 +40,20 @@
 import { CodexUnknownFieldError } from "./errors.js";
 /**
  * Build a codex-export payload from a PlaintextCodex. Stamps the current
- * `"1.3"` envelope version and `exportedAt` with the current ISO time.
+ * `"1.2"` envelope version and `exportedAt` with the current ISO time.
  * Returns the object — the caller stringifies it (so callers in a
  * memory-constrained environment can stream it out instead of holding the
  * whole string in RAM).
  *
- * The return type is the `CodexExportV1_2 | CodexExportV1_3` union so
- * consumers written against the historical 1.2 shape still type-check
- * against the widened output; the runtime value is always a 1.3 envelope.
+ * The return type is the `CodexExportV1_2 | CodexExportV1_3` union so this
+ * signature does not have to change when the writer advances to 1.3; the
+ * runtime value today is a 1.2 envelope. See the file header for why the
+ * writer trails the reader and what has to be true before it advances.
  *
- * The optional `foreignKeys` block is EMITTED only when the source codex
- * carries foreign keys. ouronet's `PlaintextCodex` has no foreign-key
- * source field today, so the practical output is a bare 1.3 envelope with
- * `foreignKeys` omitted — no mandatory empty block.
+ * The optional `foreignKeys` block belongs to the 1.3 shape and is never
+ * emitted here — ouronet's `PlaintextCodex` has no foreign-key source
+ * field — so the output carries no 1.3-only data and nothing is lost by
+ * stamping 1.2.
  *
  * Fields left out intentionally: `pureKeypairs`, `schemaVersion`,
  * `lastUpdatedAt`, `lastUpdatedDevice` — see CodexExportV1_3 JSDoc for
@@ -47,7 +61,7 @@ import { CodexUnknownFieldError } from "./errors.js";
  */
 export function buildCodexExport(codex) {
     return {
-        version: "1.3",
+        version: "1.2",
         exportedAt: new Date().toISOString(),
         kadenaWallets: codex.kadenaWallets,
         ouronetWallets: codex.ouronetWallets,
@@ -56,7 +70,7 @@ export function buildCodexExport(codex) {
     };
 }
 /**
- * Stringify a PlaintextCodex into the `"1.3"` backup JSON format, the
+ * Stringify a PlaintextCodex into the `"1.2"` backup JSON format, the
  * exact output of OuronetUI's LocalStorageCodexAdapter.downloadAsJson.
  * Pretty-prints with 2-space indent because the file lands on disk and
  * a human occasionally opens it to sanity-check account addresses.
@@ -73,7 +87,7 @@ export function serializeCodex(codex) {
  * Throws on:
  *   - invalid JSON
  *   - missing `"version"` field (malformed)
- *   - version mismatch (not `"1.2"`)
+ *   - version mismatch (neither `"1.2"` nor `"1.3"`)
  *   - shape mismatch (kadenaWallets, ouronetWallets, addressBook not arrays; uiSettings not an object)
  *
  * The version check exists to fail-fast rather than silently mis-decoding

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouronet/ouronet-core",
-  "version": "4.3.7",
+  "version": "4.4.0",
   "description": "Ouronet-specific business logic for the Ouronet protocol on StoaChain — interactions/* read+execute functions for the ouronet-ns Pact modules, the Codex encrypted-multi-wallet format, Ouronet protocol accounts and tokens. Depends on @stoachain/stoa-core for chain-generic infrastructure (signing, wallet, crypto, network, etc.).",
   "type": "module",
   "main": "./dist/index.js",