cid(advance): Add Codec operations and Constants sections to 4 binding howto guides

Author: CID Agent

.claude/agent-memory/advance/MEMORY.md

@@ -228,8 +228,12 @@ iterations.
 - zensical.toml nav: How-to Guides order is Rust → Python → Node.js → WebAssembly → Go → Java
 - Go and Java guides include algorithm primitives section (SlidingWindow, AlgMinhash256,
     AlgCdcChunks, AlgSimhash) not present in Python/Node.js guides
-- All 6 how-to guides complete: Rust (356 lines), Python (353), Node.js (281), WASM (338), Go (388),
-    Java (321)
+- All 6 how-to guides have Codec operations + Constants sections. Python, Node.js, WASM, Go all have
+    them; Java has them too. Python uniquely documents `core_opts` SimpleNamespace and IntEnum
+    return types from `iscc_decode`. WASM constants use getter functions (`meta_trim_name()` not
+    `META_TRIM_NAME`). Node.js Codec section uses `require()` style imports per next.md spec
+- All 6 how-to guides complete: Rust (356 lines), Python (~420), Node.js (~350), WASM (~410), Go
+    (463), Java (~390)
 - `docs/architecture.md` and `docs/development.md` include all 6 binding crates (Python, Node.js,
     WASM, C FFI, JNI, Go) in diagrams, layout trees, and tables. Go uses dotted arrow (`-.->`) in
     Mermaid to indicate indirect WASM dependency via `iscc-ffi`

.claude/context/handoff.md

@@ -1,42 +1,36 @@
-## 2026-02-27 — Review of: Update Go docs for 30/30 Tier 1 symbols
-
-**Verdict:** PASS_WITH_NOTES
-
-**Summary:** Clean, well-structured documentation update adding "Codec operations" and "Constants"
-sections to `docs/howto/go.md` and replacing stale "planned" text in `packages/go/README.md` with
-organized API tables covering all 30/30 Tier 1 symbols. One minor doc bug fixed during review
-(incorrect prefix claim in decompose example).
-
-**Verification:**
-
-- [x] `grep -c 'EncodeComponent' docs/howto/go.md` → 1
-- [x] `grep -c 'IsccDecode' docs/howto/go.md` → 2
-- [x] `grep -c 'IsccDecompose' docs/howto/go.md` → 1
-- [x] `grep -c 'JsonToDataUrl' docs/howto/go.md` → 1
-- [x] `grep -c 'EncodeBase64' docs/howto/go.md` → 1
-- [x] `grep -c 'SoftHashVideoV0' docs/howto/go.md` → 1
-- [x] `grep -c 'MetaTrimName' docs/howto/go.md` → 1
-- [x] `grep 'are planned' packages/go/README.md` → no matches (stale text removed)
-- [x] `grep -c 'EncodeComponent' packages/go/README.md` → 1
-- [x] `grep -c 'DataHasher' packages/go/README.md` → 2
-- [x] `uv run zensical build` → exits 0
-- [x] `mise run check` → all 14 hooks pass
-
-**Issues found:**
-
-- Minor: Decompose example comment said "Each unit code with 'ISCC:' prefix" but `iscc_decompose`
-    returns units WITHOUT the prefix (verified via Rust docstring and Go test). Fixed in review.
-
-**Codex review:** Codex identified the incorrect "ISCC:" prefix claim in the decompose example
-comment — confirmed and fixed. No other actionable findings.
-
-**Next:** All 6 language bindings have 30/30 Tier 1 symbols documented. The project can move on to
-other target milestones — likely the remaining issues in issues.md: dict auto-serialization for
-`gen_meta_code_v0` (issue #5), or adding codec/constants documentation sections to Java and Python
-howto guides for cross-language parity.
-
-**Notes:** The `SoftHashVideoV0` function is documented under "Codec operations" rather than
-"Algorithm primitives" — this follows the next.md spec but is a slight taxonomic mismatch. Not worth
-changing now; if howto guides get a structural refresh later, it could be moved. Java and Python
-howto guides don't yet have codec/constants sections — Go is the first binding with full doc
-coverage.
+## 2026-02-27 — Add Codec operations and Constants sections to binding howto guides
+
+**Done:** Added "Codec operations" and "Constants" documentation sections to all 4 binding howto
+guides (Python, Node.js, Java, WASM), achieving cross-language documentation parity with the Go
+guide. Each guide covers encode/decode, decompose, additional codec functions, and algorithm
+constants with language-idiomatic code examples.
+
+**Files changed:**
+
+- `docs/howto/python.md`: Added Codec operations section (encode/decode with IntEnum types,
+    decompose, 3 bullet-point functions), Constants section (direct imports + core_opts namespace),
+    updated front matter description and opening paragraph
+- `docs/howto/nodejs.md`: Added Codec operations section (encode/decode with IsccDecodeResult,
+    decompose, 3 bullet-point functions using require() style), Constants section (destructured
+    exports), updated front matter description and opening paragraph
+- `docs/howto/java.md`: Added Codec operations section (camelCase methods on IsccLib,
+    IsccDecodeResult with int/byte[] fields, decompose, 3 bullet-point methods), Constants section
+    (static final int on IsccLib), updated front matter description
+- `docs/howto/wasm.md`: Added Codec operations section (encode/decode with Uint8Array,
+    IsccDecodeResult, decompose, 3 bullet-point functions), Constants section (getter functions),
+    updated front matter description and opening paragraph
+
+**Verification:** All 14 grep checks pass (all ≥ 1). `uv run zensical build` exits 0.
+`mise run check` passes all 14 hooks. mdformat auto-formatted some alignment in code comments
+(removed extra alignment spaces in constants sections) — changes are clean.
+
+**Next:** All 6 language binding howto guides now have full documentation coverage (30/30 Tier 1
+symbols). The project can focus on other target milestones — the remaining issues in issues.md (dict
+auto-serialization for gen_meta_code_v0, or adding Algorithm primitives sections to Python, Node.js,
+and WASM guides).
+
+**Notes:** The Python guide uniquely documents the `core_opts` SimpleNamespace and IntEnum return
+types from `iscc_decode` — these are Python-specific API features not present in other bindings. The
+Node.js guide uses `require()` import style in the Codec sections as specified in next.md, while the
+existing Code generation sections use ESM `import` — this mirrors the Go guide's pattern of showing
+different import styles in different sections.

docs/howto/java.md

@@ -1,6 +1,6 @@
 ---
 icon: lucide/coffee
-description: Guide to using iscc-lib from Java — JNI setup, code generation, streaming, and utilities.
+description: Guide to using iscc-lib from Java — JNI setup, code generation, streaming, codec operations, constants, and utilities.
 ---
 
 # Java
@@ -296,6 +296,71 @@ Additional primitives:
 - `IsccLib.softHashVideoV0(int[][] frameSigs, int bits)` — compute a similarity-preserving hash from
     video frame signatures, returns `byte[]`
 
+## Codec operations
+
+Methods for encoding, decoding, and decomposing ISCC codes. These operate on the ISCC binary format
+defined in ISO 24138.
+
+### Encode and decode
+
+Construct an ISCC unit from raw header fields and digest, then decode it back:
+
+```java
+// Encode: maintype=0 (Meta), subtype=0, version=0, 64 bits, 8-byte digest
+byte[] digest = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};
+String code = IsccLib.encodeComponent(0, 0, 0, 64, digest);
+System.out.println(code); // ISCC unit string (without "ISCC:" prefix)
+
+// Decode: parse an ISCC unit string back into header components and digest
+IsccDecodeResult result = IsccLib.isccDecode(code);
+System.out.printf("Maintype: %d, Subtype: %d, Version: %d, Length: %d%n",
+    result.maintype, result.subtype, result.version, result.length);
+System.out.printf("Digest: %s%n", java.util.HexFormat.of().formatHex(result.digest));
+```
+
+`isccDecode` returns an `IsccDecodeResult` with `int` fields `maintype`, `subtype`, `version`,
+`length` (length index), and a `byte[]` field `digest`.
+
+### Decompose
+
+Split a composite ISCC-CODE into its individual unit codes:
+
+```java
+byte[] data = "Hello World".repeat(1000).getBytes();
+String dataCode = IsccLib.genDataCodeV0(data, 64);
+String instanceCode = IsccLib.genInstanceCodeV0(data, 64);
+String isccCode = IsccLib.genIsccCodeV0(
+    new String[]{dataCode, instanceCode}, false
+);
+
+// Decompose into individual units
+String[] units = IsccLib.isccDecompose(isccCode);
+for (String unit : units) {
+    System.out.println(unit); // Each unit code (without "ISCC:" prefix)
+}
+```
+
+### Other codec methods
+
+- `IsccLib.encodeBase64(byte[] data)` — encode bytes to base64 string
+- `IsccLib.jsonToDataUrl(String json)` — convert a JSON string to a
+    `data:application/json;base64,...` URL
+- `IsccLib.softHashVideoV0(int[][] frameSigs, int bits)` — compute a video similarity hash from
+    MPEG-7 frame signatures, returns `byte[]`
+
+## Constants
+
+Static constants on the `IsccLib` class used by the ISCC algorithms:
+
+```java
+import io.iscc.iscc_lib.IsccLib;
+
+IsccLib.META_TRIM_NAME;        // 128 — max byte length for name normalization
+IsccLib.META_TRIM_DESCRIPTION; // 4096 — max byte length for description normalization
+IsccLib.IO_READ_SIZE;          // 4_194_304 — default read buffer size (4 MB)
+IsccLib.TEXT_NGRAM_SIZE;       // 13 — n-gram size for text similarity hashing
+```
+
 ## Conformance testing
 
 Verify that the library produces correct results for all official test vectors:

docs/howto/nodejs.md

@@ -1,12 +1,12 @@
 ---
 icon: lucide/hexagon
-description: Guide to using iscc-lib from Node.js via the native addon.
+description: Guide to using iscc-lib from Node.js — code generation, streaming, codec operations, and constants.
 ---
 
 # Node.js
 
 A guide to using iscc-lib from Node.js via the `@iscc/lib` native addon. Covers installation, code
-generation, and streaming.
+generation, streaming, codec operations, and constants.
 
 ---
 
@@ -252,6 +252,85 @@ const singleLine = text_remove_newlines("Hello\nWorld");
 const trimmed = text_trim("Hello World", 5);
 ```
 
+## Codec operations
+
+Functions for encoding, decoding, and decomposing ISCC codes. These operate on the ISCC binary
+format defined in ISO 24138.
+
+### Encode and decode
+
+Construct an ISCC unit from raw header fields and digest, then decode it back:
+
+```javascript
+const {
+    encode_component,
+    iscc_decode
+} = require("@iscc/lib");
+
+// Encode: maintype=0 (Meta), subtype=0, version=0, 64 bits, 8-byte digest
+const digest = Buffer.from([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]);
+const code = encode_component(0, 0, 0, 64, digest);
+console.log(code); // ISCC unit string (without "ISCC:" prefix)
+
+// Decode: parse an ISCC unit string back into header components and digest
+const result = iscc_decode(code);
+console.log(`Maintype: ${result.maintype}, Subtype: ${result.subtype}`);
+console.log(`Version: ${result.version}, Length: ${result.length}`);
+console.log(`Digest: ${Buffer.from(result.digest).toString("hex")}`);
+```
+
+`iscc_decode` returns an `IsccDecodeResult` object with `maintype`, `subtype`, `version`, `length`
+(length index), and `digest` (Buffer) fields.
+
+### Decompose
+
+Split a composite ISCC-CODE into its individual unit codes:
+
+```javascript
+const {
+    gen_data_code_v0,
+    gen_instance_code_v0,
+    gen_iscc_code_v0,
+    iscc_decompose
+} = require("@iscc/lib");
+
+const data = Buffer.from("Hello World".repeat(1000));
+const dataCode = gen_data_code_v0(data);
+const instanceCode = gen_instance_code_v0(data);
+const isccCode = gen_iscc_code_v0([dataCode, instanceCode]);
+
+// Decompose into individual units
+const units = iscc_decompose(isccCode);
+for (const unit of units) {
+    console.log(unit); // Each unit code (without "ISCC:" prefix)
+}
+```
+
+### Other codec functions
+
+- `encode_base64(data)` — encode a Buffer to base64 string
+- `json_to_data_url(json)` — convert a JSON string to a `data:application/json;base64,...` URL
+- `soft_hash_video_v0(frameSigs, bits?)` — compute a video similarity hash from MPEG-7 frame
+    signatures, returns Buffer
+
+## Constants
+
+Exported constants used by the ISCC algorithms:
+
+```javascript
+const {
+    META_TRIM_NAME,
+    META_TRIM_DESCRIPTION,
+    IO_READ_SIZE,
+    TEXT_NGRAM_SIZE,
+} = require("@iscc/lib");
+
+META_TRIM_NAME; // 128 — max byte length for name normalization
+META_TRIM_DESCRIPTION; // 4096 — max byte length for description normalization
+IO_READ_SIZE; // 4_194_304 — default read buffer size (4 MB)
+TEXT_NGRAM_SIZE; // 13 — n-gram size for text similarity hashing
+```
+
 ## Conformance testing
 
 Verify the library against official test vectors:

docs/howto/python.md

@@ -1,12 +1,12 @@
 ---
 icon: lucide/terminal
-description: Guide to using iscc-lib from Python — code generation, streaming, and text utilities.
+description: Guide to using iscc-lib from Python — code generation, streaming, codec operations, constants, and text utilities.
 ---
 
 # Python
 
 A guide to using iscc-lib from Python. Covers installation, code generation, structured results,
-streaming, and text utilities.
+streaming, text utilities, codec operations, and constants.
 
 ---
 
@@ -329,6 +329,94 @@ trimmed = text_trim("Hello World", 5)
 print(trimmed)  # 'Hello'
 ```
 
+## Codec operations
+
+Functions for encoding, decoding, and decomposing ISCC codes. These operate on the ISCC binary
+format defined in ISO 24138.
+
+### Encode and decode
+
+Construct an ISCC unit from raw header fields and digest, then decode it back:
+
+```python
+from iscc_lib import encode_component, iscc_decode, MT, ST, VS
+
+# Encode: maintype=0 (Meta), subtype=0, version=0, 64 bits, 8-byte digest
+digest = bytes([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08])
+code = encode_component(0, 0, 0, 64, digest)
+print(code)  # ISCC unit string (without "ISCC:" prefix)
+
+# Decode: parse an ISCC unit string back into header components and digest
+mt, st, vs, length, raw_digest = iscc_decode(code)
+print(f"MainType: {mt}, SubType: {st}, Version: {vs}, Length: {length}")
+print(f"Digest: {raw_digest.hex()}")
+
+# Returned enum fields are IntEnum instances
+assert isinstance(mt, MT)
+assert isinstance(st, ST)
+assert isinstance(vs, VS)
+```
+
+`iscc_decode` returns a `tuple[MT, ST, VS, int, bytes]` with `IntEnum`-typed values for the header
+fields.
+
+### Decompose
+
+Split a composite ISCC-CODE into its individual unit codes:
+
+```python
+from iscc_lib import (
+    gen_data_code_v0,
+    gen_instance_code_v0,
+    gen_iscc_code_v0,
+    iscc_decompose,
+)
+
+data = b"Hello World" * 1000
+data_result = gen_data_code_v0(data)
+instance_result = gen_instance_code_v0(data)
+iscc_code = gen_iscc_code_v0([data_result.iscc, instance_result.iscc])
+
+# Decompose into individual units
+units = iscc_decompose(iscc_code.iscc)
+for unit in units:
+    print(unit)  # Each unit code (without "ISCC:" prefix)
+```
+
+### Other codec functions
+
+- `encode_base64(data: bytes) -> str` — encode bytes to base64
+- `json_to_data_url(json: str) -> str` — convert a JSON string to a
+    `data:application/json;base64,...` URL
+- `soft_hash_video_v0(frame_sigs, bits=64) -> bytes` — compute a video similarity hash from MPEG-7
+    frame signatures
+
+## Constants
+
+Module-level constants used by the ISCC algorithms. These are available as direct imports and also
+through the `core_opts` namespace for iscc-core API parity:
+
+```python
+from iscc_lib import (
+    META_TRIM_NAME,
+    META_TRIM_DESCRIPTION,
+    IO_READ_SIZE,
+    TEXT_NGRAM_SIZE,
+    core_opts,
+)
+
+META_TRIM_NAME  # 128 — max byte length for name normalization
+META_TRIM_DESCRIPTION  # 4096 — max byte length for description normalization
+IO_READ_SIZE  # 4_194_304 — default read buffer size (4 MB)
+TEXT_NGRAM_SIZE  # 13 — n-gram size for text similarity hashing
+
+# core_opts namespace (iscc-core compatibility)
+core_opts.meta_trim_name  # 128
+core_opts.meta_trim_description  # 4096
+core_opts.io_read_size  # 4_194_304
+core_opts.text_ngram_size  # 13
+```
+
 ## Conformance testing
 
 Verify that the library produces correct results for all official test vectors: