canon: Substrate Stack architecture + Constitutional Triangle (magical-first-run, symmetric-participation, creators-get-paid)

[klappy]

Summary

Canon promotion landing four files together as the program's constitutional commitments at the substrate, application, and economy layers:

• canon/architecture/substrate-stack.md — the OSI-equivalent layered architectural model. Six layers (L1 Wire, L2 Wrapper-Adapter, L3 Identity-Convention, L4 Role-Agent, L5 Application, L6 Economy cross-cutting) with one concern each, narrow neighbor interfaces, replaceable independently. The canonical lookup for "where does X live?" questions across the program. Includes a layer-assignment table for existing work, a "what the stack forbids" enforcement section, and explicit open questions. Also adds canon/architecture/README.md and the canon/architecture/ directory itself as a new home for structural maps and layered models — distinct from canon/principles/ (reasoning orientations), canon/decisions/ (specific committed choices), and canon/patterns/ (repeatable design templates applied at one layer).

• canon/principles/magical-first-run.md — L5 success metric. Any user-facing application on the substrate must be reachable, useful, and intelligible to a non-technical operator within sixty seconds of first contact, without protocol explanation. Success metric: unprompted use of easy and magical. TinCan is the first L5 product graded against it; future apps inherit. Forbids empty rooms, opaque participant identity, required jargon, unexplained silence, protocol surface bleeding into UX. Explains the bridge-role (Oddie as river-guide) as the mechanism that makes the principle achievable in practice.

• canon/principles/symmetric-participation.md — L1 invariant. Every peer on the substrate interacts through identical wire primitives, regardless of what or who the peer represents. Generalizes D0020's agent-as-customer commitment from customer-layer to wire-layer. Forbids any feature that would special-case the substrate by peer type. Enables BYOA / BYOC at user-facing level: bring your own agent, bring your own channel, bring your own role.

• canon/principles/creators-get-paid.md — L6 cross-cutting commitment. Substrate maintainers can monetize substrate-tier services (capacity, hosting, reference implementations, premium tiers, support, payment-rail facilitation). Adapter authors, agent builders, and role creators monetize their work directly via the Stripe agent-payment rails (D0021). The substrate is paid for what it provides; never extracts from creators' creative work. Distinguishes payment-for-value-provided (required for maintainer survival) from extraction-tax-on-rails-usage (forbidden — landlord failure mode of every prior open substrate that drifted from infrastructure into rent extraction). The agent-economy mechanism (encode-12: penny economy, Penny-onaire's Club, BraigsList, BYOK, agent UGC marketplace) is one canonical instantiation; the principle generalizes.

Relationship to existing canon

The triangle articulates what existing AMS mechanism canon (D0020, D0021, encode-12) concretely operationalizes — principles abstract, mechanisms instantiate, neither replaces the other. None of the existing klappy.dev or AMS canon is superseded; this PR adds upstream principle-tier articulation for substrate-shaping commitments that previously lived only at the AMS-tier mechanism level.

The substrate stack is canon/architecture/ rather than canon/principles/ because it functions as a structural lookup the principles cite, not as a reasoning orientation in its own right. New directory established; README added.

Voice / writing-canon compliance

Drafts written against canon/constraints/ai-voice-cliches.md — checked for negation parallelism, formulaic transitions, generic descriptors, em dash overuse, uniform pacing, sycophantic openers, summary clichés. Voice is neutral. Author voice clichés should be light or absent; expecting reviewer feedback if any cluster.

Gauntlet

• Manual URI integrity check: PASS. All klappy:// and ams:// URIs grep clean across the four files; cross-references resolve to existing canon (or to themselves for self-references). Body-text path references (canon/values/axioms.md, canon/principles/vodka-architecture.md, canon/principles/dream-house-principle.md, etc.) all verified to exist on main.
• oddkit_challenge at mode=canon-tier-1, knowledge_base_url=https://github.com/klappy/klappy.dev: status CHALLENGED, block_until_addressed: false. Matched challenge types: principle-extraction, comparative-positioning, pattern-coinage, assumption, proposal, observation, strong-claim. The challenge surfaces standard tier-1 prerequisites worth carrying into PR review and follow-up amendments — see "Known limitations" below.
• oddkit_audit is scoped to writings/ and does not cover canon/, so it is a no-op for this PR. URI integrity was checked manually instead.

Known limitations (carried forward to review)

The principles are explicitly marked stability: semi_stable / the substrate stack stability: evolving, intended to iterate from contact with reality per operator direction ("we have to start somewhere; let's go with this and iterate from contact with reality"). Specific canon-tier-1 prerequisites the current drafts do not yet fully satisfy:

• Retraction conditions not all named. Each principle should ideally state what evidence would cause it to be retracted. The substrate stack names this implicitly via "Open Questions"; the three principles do so less explicitly. Review-time amendment candidate.
• Alternatives considered not enumerated. The drafts describe what each principle commits to, not the alternative shapes that were considered and rejected. Review-time amendment candidate.
• Multi-case anchoring uneven. symmetric-participation cites four prior substrates (TCP/IP, HTTP, Unix pipes, email) via doing-less-enables-more; creators-get-paid cites prior platform failure modes (app stores, marketplaces). magical-first-run rests primarily on the planned TinCan instantiation plus the 2026-05-09 ChatGPT/TinCan diagnostic — sample-of-one. The principle's aspirational/future-governing posture makes this expected, but worth flagging.
• Reversibility statements implicit only. Constitutional principles are typically one-way doors at the positioning level (per D0020's framing); the docs do not say so explicitly.

These are quality-of-canon refinements, not correctness issues. Recommended path: land this PR as the starting point, address findings via review comments and follow-up amendment PRs that don't fragment canon.

Provenance

Operator–Claude conversation 2026-05-09. Session journaled at agent-messaging-service journal/2026-05-09-substrate-stack-and-constitutional-triangle.tsv (PR #73, 39 DOLCHE+H artifacts: 9 O, 8 L, 6 D, 5 C, 4 E, 7 H). The journal entry was committed and pushed before any of these canon files were drafted, to preserve session reasoning even if the canon-write step was interrupted.

Follow-ups (not in this PR)

• Update canon/principles/README.md index to include the three new principles in the alphabetized list. Worth a small follow-up commit once entries are reviewed and stable.
• Possible meta-index update at the-frame.md if it lists tier-1 principles.
• Oddie role-extension doc (under existing voice-canon umbrella, governs L4 behavior in AMS rooms) — separate session; requires reading canon/voice/oddie-the-river-guide.md end-to-end first.
• AMS-side P-track proposal for the binding_id wrapper ergonomic identified during the same session (highest-ROI single change in the AMS MCP wrapper) — separate AMS PR.

---

Note

Low Risk
Adds new canon documentation only (no code/behavior changes), so the primary risk is confusing or inconsistent guidance if the new architectural/principle docs conflict with existing canon.

Overview
Introduces a new canon/architecture/ section (with index README) and adds substrate-stack.md as the program’s canonical layered architecture/ownership map for where responsibilities should live across L1–L6.

Adds three new tier-1 canon principles—magical-first-run, symmetric-participation, and creators-get-paid—that define constitutional constraints for L5 UX, L1 wire invariants, and L6 monetization (anti-extraction) respectively, with cross-references back to the new substrate stack and existing AMS decisions.

^{Reviewed by Cursor Bugbot for commit 4475851. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Canon Quality — oddkit_audit ✅

No dead klappy:// references or legacy link patterns found in writings/. 39 files scanned.

_{Spec: klappy://docs/oddkit/specs/oddkit-audit · Workflow: .github/workflows/canon-quality.yml · Run: #72}