Merge pull request #3 from iscc/develop

Fix WASM howto package name and merge release fixes

Author: titusz

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

@@ -66,7 +66,13 @@ iterations.
     Cargo.toml changes needed. The cdylib target produces the `.wasm` file
 - `iscc_alloc`/`iscc_dealloc` are the WASM host memory management pair — host allocates via
     `iscc_alloc`, writes data, calls FFI functions, then frees via `iscc_dealloc`
-- Debug WASM binary is ~10.5MB; release + wasm-opt would reduce significantly
+- Debug WASM binary is ~10.5MB; release + wasm-opt reduces significantly
+- wasm-opt release config in `crates/iscc-wasm/Cargo.toml`:
+    `[package.metadata.wasm-pack.profile.release]` with
+    `wasm-opt = ["-O", "--enable-bulk-memory", "--enable-nontrapping-float-to-int"]`. Rust's LLVM
+    emits `memory.copy` (bulk-memory) and `i32.trunc_sat_f64_s/u` (nontrapping-float-to-int) — both
+    must be enabled for wasm-opt to accept the binary. If future Rust versions emit more post-MVP
+    ops, add specific `--enable-*` flags (or switch to `--enable-all` as last resort)
 - Install target: `rustup target add wasm32-wasip1`
 - Build: `cargo build -p iscc-ffi --target wasm32-wasip1`
 - Output: `target/wasm32-wasip1/debug/iscc_ffi.wasm`
@@ -110,10 +116,11 @@ iterations.
 - Go streaming hasher pattern: `DataHasher`/`InstanceHasher` structs hold `rt *Runtime` +
     `ptr   uint32` (opaque WASM pointer). Factory methods on Runtime call `iscc_*_hasher_new()` and
     check for NULL. `Update` writes bytes via `writeBytes`, calls `iscc_*_hasher_update` (returns
-    i32 as bool: 0=error, nonzero=ok). `Finalize` calls `iscc_*_hasher_finalize` (returns string
-    pointer) and uses `callStringResult`. `Close` calls `iscc_*_hasher_free` and zeroes `h.ptr` to
-    prevent double-free (fire-and-forget, safe to call multiple times). No sret ABI needed — all
-    streaming hasher FFI functions use simple i32 params/returns
+    i32 as bool: 0=error, nonzero=ok). `UpdateFrom` reads from `io.Reader` in 64 KiB chunks and
+    delegates to `Update`. `Finalize` calls `iscc_*_hasher_finalize` (returns string pointer) and
+    uses `callStringResult`. `Close` calls `iscc_*_hasher_free` and zeroes `h.ptr` to prevent
+    double-free (fire-and-forget, safe to call multiple times). No sret ABI needed — all streaming
+    hasher FFI functions use simple i32 params/returns
 - Byte-buffer-returning WASM functions use sret ABI: caller allocates 8 bytes (IsccByteBuffer or
     IsccByteBufferArray struct), passes ptr as first arg. Function writes struct fields to that ptr.
     The free functions (iscc_free_byte_buffer, iscc_free_byte_buffer_array) take the struct by
@@ -156,8 +163,37 @@ iterations.
     via regex `r'^version\s*=\s*"(.+?)"'`, updates `package.json` (json stdlib) and `pom.xml` (regex
     replacement). Supports `--check` flag. mise tasks: `version:sync`, `version:check`
 
+## Release Workflow
+
+- PR merge: `gh pr merge N --merge` (merge commit, not squash) preserves commit history
+- Tag on main: `git tag vX.Y.Z && git push origin vX.Y.Z` triggers `.github/workflows/release.yml`
+- Release workflow matches pattern `push: tags: [v*.*.*]`
+- After tagging, switch back to develop: `git checkout develop`
+- If local changes block branch switch, `git stash push -m "reason" <file>` then `git stash pop`
+    after switching back
+- OIDC trusted publishing for crates.io requires crate to exist first (first publish needs API
+    token). PyPI supports pending trusted publishers. npm uses `NPM_TOKEN` secret
+- Release workflow has 4 `workflow_dispatch` inputs: `crates-io`, `pypi`, `npm`, `maven` (all
+    boolean, default false). Jobs: `publish-crates-io`, `build-wheels`, `build-sdist`,
+    `publish-pypi`, `build-napi`, `publish-npm-lib`, `build-wasm`, `publish-npm-wasm`, `build-jni`,
+    `assemble-jar`
+- `build-jni` matrix: 5 platforms with `native-dir` and `lib-name` matrix vars matching NativeLoader
+    conventions. Artifacts named `jni-{native-dir}` (e.g., `jni-linux-x86_64`)
+- `assemble-jar` downloads `jni-*` artifacts into `jni-staging/`, iterates subdirectories to copy
+    native libs to `src/main/resources/META-INF/native/{native-dir}/`. Uses
+    `mvn package -DskipTests` and uploads JAR as `iscc-lib-jar` artifact
+- `actions/download-artifact@v4` default behavior (no `merge-multiple`) creates per-artifact
+    subdirectories named after the artifact — useful for iterating platform-specific downloads
+
 ## Documentation
 
+- Ecosystem page: `docs/ecosystem.md` — covers official (iscc-core, iscc-lib) and community
+    (iscc-core-ts) implementations. Uses `icon: lucide/globe`. Nav entry in `zensical.toml` placed
+    between "Explanation" and "Reference" as a top-level entry
+- `branciard/iscc-core-ts`: TypeScript port, Apache-2.0, v0.3.0, all 9 gen\_\*\_v0 and
+    gen_iscc_id_v0/v1 and gen_flake_code_v0. Vendors official `data.json` (66KB). 263 tests across
+    18 suites. Author: François Branciard. NGI Zero Core / NLnet funded. Status: active development,
+    not production-ready
 - How-to guide structure: YAML front matter (`icon`, `description`) → title → intro → installation →
     code generation (9 subsections: Meta, Text, Image, Audio, Video, Mixed, Data, Instance,
     ISCC-CODE) → streaming → text utilities → conformance testing → error handling
@@ -172,12 +208,18 @@ iterations.
     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)
+- `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`
 - Java guide key differences from Go: no runtime object (static methods), "Setup" section replaces
     "Runtime setup", streaming uses opaque `long` handles with try-finally (not defer),
     `genIsccCodeV0` exposes `boolean wide` parameter (Go hardcodes to false)
 - docs/index.md landing page: 6 Quick Start tabs (Rust, Python, Node.js, Java, Go, WASM) + 7
     Available Bindings table rows. All tabs use `gen_text_code_v0("Hello World")`. mdformat
     auto-reformats JS imports to multi-line style in code blocks inside tabbed markdown
+- WASM how-to (`docs/howto/wasm.md`) uses `@iscc/wasm` throughout (20 occurrences). Always verify
+    npm package names against `docs/index.md` and `crates/*/README.md` — the wasm-pack howto
+    originally had `@iscc/iscc-wasm` (wrong)
 
 ## Codec Internals
 

.claude/agent-memory/define-next/MEMORY.md

@@ -122,6 +122,18 @@ iterations.
     state.md's CI section for the latest status. When CI is red, that's always the first priority
     regardless of what the handoff "Next" section suggests. Formatting fixes are trivial single-file
     steps — don't over-scope them.
+- **Release milestone steps** (iteration 2, second loop): When all code is complete and CI is green,
+    the remaining work is operational (merge PRs, tag releases). These are zero-file-change steps
+    that use `gh` and `git` commands exclusively. Verify preconditions (PR mergeable, CI green)
+    before scoping, and call out what NOT to do (don't squash, don't delete develop, don't wait for
+    release workflow). When an existing PR already covers the merge, update its title/body rather
+    than creating a new one.
+- **Post-release build fixes** (iteration 3, second loop): When a release workflow partially fails,
+    the fix often belongs in crate-level config (e.g., `Cargo.toml` metadata sections) rather than
+    the workflow YAML. wasm-pack supports `[package.metadata.wasm-pack.profile.release]` for
+    configuring wasm-opt flags — this is the portable, documented approach that works both locally
+    and in CI. Prefer crate-config fixes over workflow-command-line fixes for reproducibility. After
+    fixing, don't re-trigger the release in the same step — that's a separate human-gated operation.
 
 ## Architecture Decisions
 
@@ -186,4 +198,38 @@ iterations.
 - Maven's working directory is the pom.xml parent directory, not the workspace root.
 - ISCC Foundation URL is `https://iscc.io` — not iscc.foundation or other variants.
 - WASM howto guide at `docs/howto/wasm.md` has wrong package name `@iscc/iscc-wasm` — correct name
-    is `@iscc/wasm` per learnings. Pre-existing issue not yet fixed.
+    is `@iscc/wasm` per learnings. Being fixed in iteration 5 (second CID loop).
+- **Pairing doc fixes with PRs** (iteration 5, second loop): When the next step is creating a PR
+    (develop → main), pair it with any pending doc fixes that would ship in that merge. The WASM
+    howto package name fix was a known issue sitting in agent memory — fixing it before the PR means
+    the corrected docs deploy from main immediately. This avoids an extra iteration just for the
+    fix. Good pairing criteria: same branch, no code risk, verifiable by grep.
+- **Remaining state→target gaps after v0.0.1**: Maven Central publishing, crates.io OIDC, npm token
+    setup — all require human action on external services. The TypeScript port evaluation (low
+    issue) is CID-actionable but low priority.
+- **Go io.Reader streaming** (iteration 7, second loop): When the handoff says "maintenance mode"
+    but the target architecture description mentions a feature ("io.Reader support for streaming")
+    that isn't implemented, that's still a valid gap to close. `UpdateFrom(ctx, io.Reader)` is 2
+    methods + 3 tests, well under the 3-file limit. It delegates to existing `Update`, so no WASM
+    changes. Prefer concrete code improvements over research tasks (TypeScript evaluation) even when
+    the handoff suggests the latter.
+- **Research + docs hybrid steps** (iteration 8, second loop): When the only remaining CID-
+    actionable item is a research task (evaluating an external repo), combine it with a concrete
+    deliverable (a new docs page) so the step is verifiable. The advance agent uses
+    WebFetch/deepwiki to examine the external repo, then creates a documentation page with findings.
+    Scope: 1 create (docs page) + 1 modify (nav config) = well under the 3-file limit. Key: be
+    factual and neutral about third-party conformance — state what was observed, not assumptions.
+- **Java native bundling in release workflow** (iteration 5, second loop): The `build-jni` +
+    `assemble-jar` pattern mirrors the existing `build-napi` + `publish-npm-lib` pattern. Key
+    differences: (1) NativeLoader expects `META-INF/native/{os}-{arch}/{libname}` directory
+    convention, (2) Maven `src/main/resources/` is auto-included in JAR (no pom.xml changes), (3)
+    the assemble-jar step collects artifacts and runs `mvn package -DskipTests`. This is CID-
+    actionable — no human credentials needed for the build step. Maven Central publishing is a
+    separate future step (requires GPG + Sonatype credentials).
+- **Stale documentation pages after binding additions** (iteration 9, second loop): When new
+    bindings are added over multiple iterations (JNI in iter 5, Go in iter 6-7), docs pages written
+    earlier (architecture.md, development.md) become stale — they miss the new crates in diagrams,
+    layout trees, and summary tables. The state assessment may say "Documentation: met" because
+    top-level target verification criteria are met, but detailed spec gaps remain. These are safe,
+    docs-only steps (2 files, no code changes). Check for: mermaid diagrams, workspace layout trees,
+    crate summary tables, streaming pattern tables, conformance test matrix tables.

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

@@ -47,13 +47,19 @@ Review patterns, quality gate knowledge, and common issues accumulated across CI
 - Python-only changes: `mise run check` + `pytest` is sufficient; skip `cargo test` and `mvn test`
     unless Rust/Java code was also modified
 
-- Go-only changes: `mise run check` + `mise exec -- go test ./...` is sufficient
+- Go-only changes: `mise run check` + `cd packages/go && mise exec -- go test ./...` is sufficient
+    (must `cd` into the Go module directory — running from repo root with `./packages/go/` path
+    fails with "cannot find main module")
 
 - Full test suite (159 tests) runs in \<1s — always run it for Python changes
 
 - Script-only changes (new Python scripts, mise task additions): `mise run check` + direct script
     invocation is sufficient — skip all test suites unless the script modifies test infrastructure
 
+- Config-only changes (Cargo.toml metadata, wasm-pack profiles, CI workflow YAML): `mise run check`
+    \+ `cargo check -p <crate>` is sufficient. If wasm-pack config changed, also run
+    `wasm-pack build --target web --release crates/iscc-wasm` to verify end-to-end
+
 ## Verification Patterns
 
 - `grep -c` counts ALL matching lines including function definitions — when next.md specifies "4

.claude/agent-memory/update-state/MEMORY.md

@@ -63,11 +63,11 @@ Codepaths, patterns, and key findings accumulated across CID iterations.
 
 ## Gotchas
 
-- `packages/go/` (iteration 13, commit c22fa53): `iscc.go` now 1,165 lines — 23/23 Tier 1 symbols
-    including `DataHasher` + `InstanceHasher` streaming types (New\*/Update/Finalize/Close lifecycle
-    wrapping WASM FfiDataHasher/FfiInstanceHasher). `iscc_test.go` 1,069 lines — 36 func
-    declarations (TestMain + 35 tests including 8 streaming hasher tests). Update takes `[]byte`,
-    NOT `io.Reader` — architecture gap noted. WASM binary gitignored; TestMain skips if missing.
+- `packages/go/` (iteration 13, commit c22fa53; updated iteration 7, commit 84ddb1b): `iscc.go` now
+    1,220 lines — 23/23 Tier 1 symbols including `DataHasher` + `InstanceHasher` with
+    `New*/Update/UpdateFrom/Finalize/Close` lifecycle. `iscc_test.go` now 1,208 lines — 39 test
+    functions, 93 subtests including `TestDataHasherUpdateFrom` and `TestInstanceHasherUpdateFrom`.
+    `io.Reader` gap resolved in iteration 7. WASM binary gitignored; TestMain skips if missing.
 - Per-crate READMEs: all 7 done (iscc-lib, iscc-py, iscc-napi, iscc-wasm, iscc-jni, packages/go,
     iscc-ffi). iscc-ffi/README.md created in iteration 29 (123 lines). packages/go/README.md created
     in iteration 10 (commit a60a375).
@@ -212,5 +212,56 @@ Codepaths, patterns, and key findings accumulated across CID iterations.
     flat-buffer functions `gen_video_code_v0_flat` + `soft_hash_video_v0_flat`; type signatures
     updated to `Sequence[Sequence[int]]`; API symbol count in target.md and specs/rust-core.md
     updated 22→23 (correcting a pre-existing under-count). **RESULT: CI FAILING** — Python ruff
-    format check fails (runs 22401304896 + 22401336439). Fix by running
+    format check fails (runs 22401304896 + 22401336439). Fixed by running
     `uv run ruff format crates/iscc-py/python/` and committing.
+- **ruff format fix (iteration 31, commit 3c0d70b)**: `_lowlevel.pyi` `gen_video_code_v0` signature
+    split across multiple lines to satisfy ruff line-length limit. Review PASS. CI now fully green:
+    all 7 jobs SUCCESS on develop (runs 22401871901 + 22401873404). Python status: MET. All
+    subsections passing. Next logical step: PR develop → main + tag v0.0.1.
+- **v0.0.1 release (iteration 32, commit 56e274d)**: PR #2 merged (develop → main, commit
+    `4bdc899`). v0.0.1 tag pushed. Release workflow run 22402189532: PyPI published ✅ (all 4 wheel
+    platforms + sdist), crates.io failed (OIDC not configured on registry — human task), WASM build
+    failed (wasm-opt rejects `memory.copy` without `--enable-bulk-memory` — fix in release.yml), npm
+    @iscc/lib + @iscc/wasm skipped. CI on develop: all 7 jobs pass (run 22402375410). CI on main:
+    all jobs pass (run 22402167393). Docs on main: pass (run 22402167413).
+- **WASM release build bug FIXED (iteration 4, commit f1ada07)**:
+    `[package.metadata.wasm-pack.profile.release]` section added to `crates/iscc-wasm/Cargo.toml`
+    with `wasm-opt = ["-O", "--enable-bulk-memory",   "--enable-nontrapping-float-to-int"]`. Both
+    flags required: `--enable-bulk-memory` for `memory.copy` (Rust uses bulk memory for memcpy),
+    `--enable-nontrapping-float-to-int` for DCT/codec float-to-int conversions. Fix verified locally
+    (29.36s release build success) and in CI WASM job (run 22403019335, SUCCESS). Fix is on
+    `develop`; needs PR → main + re-release to publish `@iscc/wasm`.
+- **wasm-pack profile config**: The correct way to configure wasm-opt flags for wasm-pack is via
+    `[package.metadata.wasm-pack.profile.release]` in `Cargo.toml`, NOT via command-line args in CI.
+    This keeps the config close to the code and works for both local and CI builds.
+- **docs/howto/wasm.md package name fixed (iteration 5, commit 1023080)**: All 20 occurrences of
+    `@iscc/iscc-wasm` replaced with `@iscc/wasm`. PR #3 open (develop → main) with both the wasm-opt
+    fix and this package name fix. CI on develop fully green: all 7 jobs pass (run 22403499473). Two
+    CI runs in progress: push to develop (22403598203) and PR #3 check (22403597692). Loop is in
+    maintenance mode — no CID-actionable code work pending. Human actions needed: merge PR #3, then
+    re-trigger release to publish @iscc/wasm and @iscc/lib to npm; crates.io OIDC setup also human.
+- **JNI cross-platform build added to release.yml (iteration 6, commits e6fe6bc+a0f2d3d)**:
+    `build-jni` job (5-platform matrix: linux-x86_64, linux-aarch64, macos-aarch64, macos-x86_64,
+    windows-x86_64) and `assemble-jar` job added to `release.yml`. `maven` boolean input checkbox
+    added to `workflow_dispatch`. `native-dir` values match `NativeLoader.java` path conventions
+    exactly (`META-INF/native/{os}-{arch}/{libname}`). CI all 7 jobs pass on develop (run
+    22404197625, HEAD `a0f2d3d`). `NativeLoader.java` path:
+    `crates/iscc-jni/java/src/main/java/io/iscc/iscc_lib/NativeLoader.java`. Java Bindings status:
+    partially met (release workflow now has native bundling jobs; Maven Central publishing still
+    missing). PR #3 still open.
+- **io.Reader streaming added to Go bindings (iteration 7, commits 84ddb1b+4c942dd)**:
+    `UpdateFrom(ctx, io.Reader)` added to both `DataHasher` and `InstanceHasher` in
+    `packages/go/iscc.go`; 64 KiB buffer, delegates to `Update`. 4 new test functions added
+    (`TestDataHasherUpdateFrom`, `TestInstanceHasherUpdateFrom`). `iscc.go` now 1,220 lines;
+    `iscc_test.go` now 1,208 lines; 39 total test functions, 93 subtests. Go Bindings status:
+    **MET** (was partially met). CI all 7 jobs pass on develop (runs 22404891331 + 22404890215, HEAD
+    `4c942dd`). **All 7 binding sections now "met"**. Loop is in maintenance mode. PR #3 still open.
+    Next CID-actionable step: await new target.md goals.
+- **Ecosystem docs page added (iteration 8, commits daf2831+de0b17a)**: `docs/ecosystem.md` (100
+    lines) created with Official Implementations section (iscc-core Python reference, iscc-lib Rust
+    polyglot) and Community Implementations section (iscc-core-ts TypeScript port by François
+    Branciard, NGI Zero Core funded, 263 tests, 9 gen\_\*\_v0 functions, not yet production-ready).
+    "Contributing an Implementation" section with 3-step guide. `icon: lucide/globe` front matter.
+    `zensical.toml` updated with `{ "Ecosystem" = "ecosystem.md" }` between Explanation and
+    Reference. Documentation page count: 14 (was 13). CI all 7 jobs pass on develop (runs
+    22405571444 + 22405570077, HEAD `de0b17a`). PR #3 still open (now includes ecosystem page too).