uor-foundation-sdk

Procedural-macro ergonomics for composing uor-foundation partition-algebra shapes.

Purpose

uor-foundation-sdk supplies three procedural macros — product_shape!, coproduct_shape!, cartesian_product_shape! — that emit ConstrainedTypeShape impls and inherent witness-minting helpers for partition-algebra constructions between two operand shapes. The crate sits a layer above uor-foundation's witness types and VerifiedMint trait, providing a compile-time ergonomics surface for building product / coproduct / Cartesian-product shapes without hand- authoring their CONSTRAINTS arrays and mint-input structs.

Dependency model

A consumer crate using these macros must take both uor-foundation and uor-foundation-sdk in [dependencies]:

[dependencies]
uor-foundation = "0.3"
uor-foundation-sdk = "0.3"

The proc macros emit absolute paths like ::uor_foundation::ConstrainedTypeShape that resolve in the consumer's dependency graph, not in uor-foundation-sdk's. This is a proc-macro-crate constraint: types from the proc-macro crate's own dependencies cannot be referenced in the emitted token stream because macro expansion happens before name resolution in the consumer's scope. uor-foundation-sdk depends on uor-foundation only for build-time type checking of the crate's own internal tests.

Macro inventory

`product_shape!(Name, A, B)`

Emits a zero-sized struct Name implementing ConstrainedTypeShape as the partition-algebra product of A and B:

SITE_COUNT = A::SITE_COUNT + B::SITE_COUNT
SITE_BUDGET = A::SITE_BUDGET + B::SITE_BUDGET
CONSTRAINTS = A's constraints concatenated with B's constraints (each B-entry is site-shifted by A::SITE_COUNT)

Also emits an inherent helper Name::mint_product_witness(...) that assembles a PartitionProductMintInputs with shape-derived fields filled in from associated-const reads and delegates to <PartitionProductWitness as VerifiedMint>::mint_verified.

use uor_foundation_sdk::product_shape;

product_shape!(AB, A, B);

let witness = AB::mint_product_witness(
    8,                  // witt_bits
    fp_a, fp_b,         // operand fingerprints
    0, 0,               // operand Eulers
    0.0, 0.0,           // operand entropies
    0, 0.0,             // combined Euler + entropy
    fp_ab,              // combined fingerprint
)?;

`coproduct_shape!(Name, A, B)`

Emits Name as the partition-algebra coproduct of A and B:

SITE_COUNT = max(A::SITE_COUNT, B::SITE_COUNT) + 1 (the "+1" is the tag-site bit)
CONSTRAINTS = A's constraints ∪ one tag-pinner Affine (bias 0) ∪ B's constraints ∪ one tag-pinner Affine (bias −1); the two tag-pinner coefficient slices are generated by the macro at expansion time.

Also emits Name::mint_coproduct_witness(...) which additionally wires the combined constraint array, left_constraint_count, and tag_site per amendment §4b'.

`cartesian_product_shape!(Name, A, B)`

Emits Name with both ConstrainedTypeShape and CartesianProductShape impls, so primitive_cartesian_nerve_betti::<Name>() routes through the Künneth formula for computing combined Betti numbers.

Emits Name::mint_cartesian_witness(...) that targets CartesianProductWitness (axiomatic-invariant validator, no structural constraint audit per amendment §3c).

Operand-support caveat

The SDK macros support operands whose CONSTRAINTS contain only these ConstraintRef variants:

Residue, Hamming, Depth, Carry, Site, SatClauses, Bound

Operands containing Affine or Conjunction variants are not supported. The const-fn primitive that shifts site indices cannot rebuild a shifted Affine coefficient slice at const-evaluation time (materializing a &'static [i64] of length original + offset from another &'static [i64] requires features Rust's stable const-eval does not provide). For the same structural reason, Conjunction sub- constraint arrays cannot be walked at const-eval time.

When an unsupported variant appears, the SDK emits a sentinel ConstraintRef::Site { position: u32::MAX }. This causes the resulting shape's witness mint to fail at a typed impossibility witness rather than silently produce incorrect topology — consumers see the error at cargo check time on the consumer crate.

Consumers needing those operand variants use the manual-construction pattern from the Product/Coproduct Completion Amendment's §Gap 2 (hand-author a fixed-size [ConstraintRef; N] array with the shifted coefficient slices written out explicitly).

Canonical variant ordering

Proc macros run before type resolution, so the macros cannot read A's or B's content fingerprints (which are only known at runtime after hashing CONSTRAINTS). The macros instead order operands by lexicographic comparison of the two Ident token spellings — a syntax-deterministic proxy for amendment §4e canonical ordering.

This means coproduct_shape!(AB, A, B) and coproduct_shape!(AB, B, A) emit identical code whenever "A" < "B", and different code otherwise. The different-code case is intentional: the witness's algebra_id will distinguish the L-R ordering, which is the amendment-specified behavior for non-canonically-ordered operands.

License

Apache-2.0.

uor-foundation-sdk 0.3.2