capglyph-core

Canonical Rust core for CapGlyph — pure codec and carrier primitives shared with capglyph-cli, capglyph-wasm, and capglyphd.

Extracted from CapGlyph/capglyph-cli crates/capglyph-core in CTX-0040.
This is the canonical Rust implementation after extraction. The former embedded crates/capglyph-core directory was removed; capglyph-cli depends on sibling ../capglyph-core. JS/Python binding hooks do not yet provide built WASM/PyO3 packages; the SDKs currently use independent framing implementations.

What it contains

Module	Purpose
carrier	Carrier trait + canonical DctCarrier/DwtCarrier + AlphaCarrier (presence-only)
dct	8×8 DCT coefficient lattice, placement, presence, secret, framed-bit, and recipient-ID primitives
dwt	2D Haar transform and LL/LH/HL/HH decomposition primitives
dwt_embed	Haar LH-band Skeleton/Edge/Prng placement, embedding, verification, framed-bit, secret, and recipient-ID primitives
ecc	Channel coding: Repetition8, BCH, RsInterleaved + SoftBit LLR + Profile
framing	CBOR version/len/type + HMAC framing (seal/open)
geometry	GeometryFile (Chaikin-smoothed polylines, JSON v1) + AnalysisParams
interleave	Burst-error interleaving (interleave/deinterleave)
keying	HKDF-SHA256 KeyMaterial {K_embed,K_mac,K_object} + PRF helpers
registration	Registration trait (Identity, Translation, NCC) + CoverVault/HybridMatch residual extraction
signal	SignalMetrics for alpha-channel presence detection
placement	Placement enum
spread_spectrum	Legacy repetition-8 shim (replaced by ecc::Profile::Repetition8)

For DWT, Skeleton, Edge, and Prng are canonical LH-band placement arms. All three use the exact unique Skeleton-position count as their comparison budget. Prng derives a platform-stable seed from the sorted Skeleton lattice; Edge ranks absolute LH energy with deterministic coordinate tie-breaking. Invalid/empty geometry, a short edge candidate set, or insufficient sync/ID capacity fails closed before image mutation. Sync and recipient-ID coordinates are selected as explicitly disjoint sets.

These implemented placement arms conflict with the stable-draft spec's Skeleton-only DWT rule. See the implementation reconciliation; code support is not a claim of full spec conformance.

Explicitly not here: clap, glob, tracing-subscriber, c2pa, trustmark/trustmark-ONNX, tiny-skia, vectomancy-raster/geometry, image-to-geometry analysis, filesystem I/O, and CLI embed/verify/extract/batch/c2pa/learned orchestration.

WASM invariant

cargo tree --target wasm32-unknown-unknown | grep -E 'clap|glob|trustmark|c2pa'
# expect no output
cargo check --lib --target wasm32-unknown-unknown

This crate must stay wasm32-unknown-unknown clean. It has no clap/glob/c2pa/trustmark dependencies; image is gated to png+jpeg only.

Usage

[dependencies]
capglyph-core = { path = "../capglyph-core" }          # isolated monorepo
# or, once published:
# capglyph-core = "0.1"
# or via git for CI without crates.io:
# capglyph-core = { git = "https://github.com/CapGlyph/capglyph-core", tag = "v0.1.0" }

use capglyph_core::{ecc::Profile, framing, keying::KeyMaterial};

// Public demonstration key/token; obtain production values from trusted key management.
let keys = KeyMaterial::from_keys([0x11; 32], [0x22; 32]);
let payload = framing::credential_payload(&[0x33; 16]);
let sealed = framing::seal(&payload, &Default::default(), keys.k_mac());
let coded = capglyph_core::ecc::encode(&sealed, Profile::Repetition8);
assert_eq!(sealed.len(), 57);
let (header, recovered) = framing::open(&sealed, keys.k_mac()).unwrap();
assert_eq!(framing::credential_token_id(&recovered, header.flags).unwrap(), [0x33; 16]);
println!("sealed bytes {}, coded bits {}", sealed.len(), coded.len());

The coefficient lattices and concrete DctCarrier/DwtCarrier implementations are canonical here. Frontends supply RGB buffers, GeometryFile, and Placement; geometry analysis and command orchestration remain frontend responsibilities. The CLI facade now re-exports/delegates to these core implementations. This example exercises framing and encoding, not image embedding or robustness.

Development

cargo build
cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo tree --target wasm32-unknown-unknown
cargo check --target wasm32-unknown-unknown

Workspace layout (isolated monorepo)

/mnt/data/Workspace/Projects/capglyph/
  capglyph-cli/     → CapGlyph/capglyph-cli  (binary, depends on ../capglyph-core via path)
  capglyph-core/    → CapGlyph/capglyph-core (this repo, standalone core)
  vectomancy -> /mnt/data/Workspace/Projects/vectomancy/vectomancy  (symlink for raster/geometry)

capglyph-cli/Cargo.toml declares:

[dependencies]
capglyph-core = { path = "../capglyph-core" }
# legacy embedded path "crates/capglyph-core" removed in CTX-0040

CI for capglyph-cli checks out CapGlyph/capglyph-core alongside CapGlyph/capglyph-cli and Xuepoo/vectomancy so the sibling path resolves (see capglyph-cli/.github/workflows/ci.yml).

Version

capglyph-core is 0.1.0 (version reset per CTX-0044). The current CLI/server manifests are 0.1.7; repository versions are not the same as the spec 1.0.1 or wire version 1. These checkout versions do not establish registry publication.

License

Apache-2.0. See LICENSE.