Skip to content

examples: add 102 N Lang example packages of the Spec surface - #9

Merged
scott-wyatt merged 2 commits into
mainfrom
nlang-spec-examples
Nov 15, 2026
Merged

scott-wyatt merged 2 commits into
mainfrom
nlang-spec-examples

Conversation

@scott-wyatt

Copy link
Copy Markdown
Contributor

What

102 N Lang example packages under examples/nlang/, one directory each, every one depending on the committed Spec bundle snapp/aph@0.1.0.nbin and exercising one corner of the Spec's surface. The directory README lists the ten families.

Why

Worked examples of the typed surface, compiled and tested against the real bundle, so a reader or a tool has something smaller than the Spec itself to learn the shapes from. The examples follow the wire vocabulary the signed fixtures use (lower-case channel kinds, DM, AlwaysAllow / AskEveryTime / NeverAllow, per-channel / per-recipient).

Verification

From the repository root, for any package:

nlang check -r examples/nlang/<name>
nlang test  -r examples/nlang/<name>

All 102 report Check passed and every test passes under nlang 0.1.0-dev (2cf4da823); 307 tests in total, one assertion each.

Hygiene

  • No JSON under examples/nlang/, so the examples manifest tripwire and the four tests that enumerate examples/*.json are untouched.
  • Identifiers are RFC 2606 names, 555-0100 phone numbers, and the published test-vector did:keys already used by the signed fixtures. Proof values and mandate signatures are well formed but illustrative, and say so.
  • .gitignore gains **/.n/deps/: the compiler materializes the resolved dependency there when it checks a package.
  • The dependency is pinned by relative path for now; at publish the from field becomes the registry coordinate @com::squillo/aph@0.1.0 with the same integrity digest.

Each directory under examples/nlang/ is one N Lang package that depends on
the committed Spec bundle, snapp/aph@0.1.0.nbin, pinned by relative path and
by the SHA-256 of its bytes, and exercises one corner of the surface: a full
envelope per channel kind, every content class, delegation and communication
mandates, the three policy decisions and both attestation modes, both flows
with their roles and operations, every refusal code with the state that
triggers it, discovery records and a key rotation, act classification and
audiences, both cryptosuites and a detached JWS, and every vault mutation
kind.

All 102 pass `nlang check` and `nlang test` under nlang 0.1.0-dev
(70349e59d), against the bundle committed beside them. The integrity pin is
the SHA-256 of that committed artifact, so a re-emit of the bundle must
re-pin the examples in the same change. Body digests are real SHA-256 over the text shown and sizes are
byte lengths; people, organizations and hosts use RFC 2606 names; did:key
identifiers are the RFC 8032 and RFC 6979 test-vector keys the signed JSON
fixtures already use; proof values and mandate signatures are illustrative.

The path form of the dependency pin is for development inside this
repository; at publish the `from` field becomes the registry coordinate
@com::squillo/aph@0.1.0 and the integrity digest stays the same.

The compiler materializes resolved dependencies under a package's .n/deps/
when it checks it; .gitignore now covers that beside .n/build/ and .n/wal/.
Every example package under examples/nlang/ pins snapp/aph@0.1.0.nbin by
the SHA-256 of its bytes. The first bundle re-emit after the examples landed
moved those bytes under every pin, and each package then failed the
compiler's dependency rung before a single test ran. The failure was found
by a downstream consumer, not here.

This test reads every example's integrity line and requires it to equal the
SHA-256 of the bundle committed beside it, so a re-emit that leaves the
examples behind fails its own change at `cargo test`. Zero examples is a
failure too. No transpiler takes part, so it runs in public CI with no skip.
A second test pins the alphabet: sixty-four lowercase hex digits, which is
how the compiler compares the field.

The examples README gains the one-line re-pin to run with every re-emit.
@scott-wyatt
scott-wyatt merged commit 63fa269 into main Nov 15, 2026
9 checks passed
@scott-wyatt
scott-wyatt deleted the nlang-spec-examples branch November 15, 2026 14:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant