From e3d144528be4c72e3aa532016ce150438b064b4d Mon Sep 17 00:00:00 2001 From: "Claude (session)" Date: Sat, 9 May 2026 14:22:46 +0000 Subject: [PATCH 1/2] canon/architecture: add Substrate Stack as new first-class architecture canon MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds canon/architecture/ as a new directory housing 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). The Klappy Substrate Stack is the inaugural architecture document: a 6-layer model (L1 Wire, L2 Wrapper-Adapter, L3 Identity-Convention, L4 Role-Agent, L5 Application, L6 Economy cross-cutting) that functions as the canonical lookup for 'where does X live?' questions across the program. Each layer has one concern, narrow neighbor interfaces, and can be replaced without disturbing the others. Includes layer-assignment table for existing work (AMS broker → L1, MCP wrapper and channel adapters → L2, ams.convention.v1 → L3, Oddie and other agents → L4, TinCan portal → L5, penny economy and Stripe rails → L6) and an enforcement section listing what the stack forbids (wire opinions about peer type; wrapper application semantics; first- party application-layer features inside the substrate, per AMS D0020). Stability: evolving. Iteration from contact with reality. Companion principles (magical-first-run, symmetric-participation, creators-get-paid) land in a follow-up commit on this branch and cite this architecture document as their structural reference. 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). --- canon/architecture/README.md | 41 ++++++ canon/architecture/substrate-stack.md | 175 ++++++++++++++++++++++++++ 2 files changed, 216 insertions(+) create mode 100644 canon/architecture/README.md create mode 100644 canon/architecture/substrate-stack.md diff --git a/canon/architecture/README.md b/canon/architecture/README.md new file mode 100644 index 0000000..2330191 --- /dev/null +++ b/canon/architecture/README.md @@ -0,0 +1,41 @@ +--- +uri: klappy://canon/architecture +title: "Architecture" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: stable +tags: ["architecture", "index"] +relevance: routing +execution_posture: routing +--- + +# Architecture + +Structural maps and layered models for the program. Architecture documents define how the system's parts fit together — the layers, the interfaces, the orthogonality contracts. Principles say *why* things are designed a certain way; architecture documents say *where each thing lives* and *how the layers compose*. + +The directory exists so questions of the form "where should X live?" become layer-lookups against an explicit map rather than opinion-fights at design time. Architecture is the canon's structural reference. + +--- + +## Contents + +| File | Title | +|------|-------| +| `substrate-stack.md` | The Klappy Substrate Stack — OSI-Equivalent Layered Architecture for the Program | + +--- + +## When to Add an Architecture Document + +Add to `canon/architecture/` when the artifact is: + +- A layered model defining where concerns live across the system. +- A structural diagram or topology with normative authority. +- An orthogonality contract — a specification of what each layer must and must not own. +- A composition reference for how parts of the program fit together. + +Use `canon/principles/` when the artifact is a reasoning orientation. Use `canon/decisions/` when the artifact records a specific choice made and committed. Use `canon/patterns/` when the artifact is a repeatable design template applied at one layer. + +The substrate stack is `architecture` rather than `principles` because it functions as a structural lookup the principles cite, not as a reasoning orientation in its own right. diff --git a/canon/architecture/substrate-stack.md b/canon/architecture/substrate-stack.md new file mode 100644 index 0000000..ebbfdaa --- /dev/null +++ b/canon/architecture/substrate-stack.md @@ -0,0 +1,175 @@ +--- +uri: klappy://canon/architecture/substrate-stack +title: "The Klappy Substrate Stack — OSI-Equivalent Layered Architecture for the Program" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: evolving +tags: ["canon", "principle", "architecture", "layered-model", "substrate", "vodka-architecture", "orthogonality", "OSI-equivalent", "ams", "tincan", "oddie"] +epoch: E0008.5 +date: 2026-05-09 +derives_from: "canon/principles/vodka-architecture.md, canon/principles/doing-less-enables-more.md, canon/principles/dream-house-principle.md, ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate, ams://canon/decisions/D0006-dream-house-wire-edge-wrappers" +complements: "canon/principles/magical-first-run.md, canon/principles/symmetric-participation.md, canon/principles/creators-get-paid.md, canon/voice/oddie-the-river-guide.md" +governs: "Where any concern, feature, decision, or product lives in the program. The canonical lookup that replaces opinion-fights about which layer should own a responsibility. Applies to AMS substrate work, TinCan and other applications, role-runtimes like Oddie, channel adapters, and economic mechanisms." +status: active +--- + +# The Klappy Substrate Stack — OSI-Equivalent Layered Architecture for the Program + +> Six layers, each with one concern, talking only to neighbors through narrow interfaces. The stack exists so the question "where does X live?" becomes a layer lookup rather than an argument. Every layer can be replaced without disturbing the others. Every layer can be implemented many times by many parties. The stack is the orthogonality contract that lets the substrate stay vodka while the products above it stay opinionated. + +--- + +## Summary — The Architectural Map + +The Klappy program builds substrates and the products that ride on them. Without an explicit stack, every architectural conversation re-litigates which layer should own a concern. Should the broker know about identity? Should TinCan ship Oddie? Does the wrapper hold the magic-link, or does the wire? The answers feel obvious in the moment and contradictory across moments. The result is layer-creep: every product accumulates concerns from layers above and below it until the code stops being replaceable. + +The substrate stack fixes this by drawing the layers explicitly and binding each to one concern. New decisions look up which layer owns the concern they touch. Cross-layer features are flagged as suspicious by default. The stack is empirical, derived from what the program has actually built (AMS, TinCan, Oddie, the MCP wrapper, the planned channel adapters and agent-economy rails) plus what the working substrates of computing history teach (`canon/principles/doing-less-enables-more.md`). + +The model is named "Substrate Stack" rather than copying OSI verbatim because the layers do not match OSI's; the orthogonality discipline is the same. + +--- + +## Outline + +- The Six Layers +- The Cross-Cutting Layer: Economy +- How to Use the Stack +- Layer Assignments for Existing Work +- What the Stack Forbids +- Open Questions +- See Also + +--- + +## The Six Layers + +### L1 — Wire + +The transport layer for frames between accounts. Knows nothing about who, why, or what the frames mean. Ships only the primitives every consumer needs and benefits from being centralized: account credentials, conversation minting, stream attachment, frame delivery, selective subscription, buffering as a substrate primitive. Vodka by definition. + +Canonical implementation: AMS. Governing decisions: `ams://canon/decisions/D0006-dream-house-wire-edge-wrappers`, `ams://canon/decisions/D0017-selective-subscription`, `ams://canon/decisions/D0018-multi-stream-per-account-per-conversation`. + +### L2 — Wrapper / Adapter + +The translation layer between L1 and a specific runtime, channel, or external protocol. Bidirectional. Holds connection state, credential mapping, payload shape, and any runtime-specific resilience logic. Carries no application opinion. + +The MCP edge wrapper, which lets MCP-speaking runtimes reach the wire, is the reference implementation. Channel adapters (WhatsApp, Slack, Discord, SMS, email, cron, GitHub) and AI-tool adapters (ChatGPT connector, Cursor, Lovable, n8n) all share this shape: they translate channel-native events into L1 frames and back. Many implementations, single shape. + +A wrapper that starts holding application semantics has stopped being a wrapper. The test: can this wrapper be removed and replaced by another implementation of the same shape, without anything above L2 noticing? If no, the wrapper has accumulated concerns from L3 or above and needs trimming. + +### L3 — Identity & Convention + +The metadata layer that gives peers human-legible identity. Who is on the wire, what role they play, what they can do, what posture they hold (always-on, intermittent, observer). Conveyed through frames the wire transports as opaque content. The wire never reads them; everything from L4 up does. + +The canonical convention shape is `ams.convention.v1` (in development): a peer joining a room posts an identity frame declaring name, role, function, model or client information when applicable, posture, and capabilities. Snapshot frames carry the resolved peer roster plus current goal and recent state for late joiners. Completion frames signal end-of-collaboration with evidence. + +L3 conventions are open: anyone can adopt them, anyone can extend them, anyone can publish their own. The wire treats every metadata shape identically. The convention's value comes from broad adoption by behavior, never from protocol-level enforcement. + +### L4 — Role / Agent + +The behavior layer. What a peer does once it is on the wire. Encompasses autonomous agents (ChatGPT, Claude, Grok, custom agents), domain-specialist agents (a code reviewer, a translator, a contract analyzer), and methodology-personification roles (Oddie as river guide, future truthkit-derived roles for other domains). + +L4 behavior is canon-driven where the role is methodology-bound. Oddie reads `klappy://canon/voice/oddie-the-river-guide` and the oddkit canon at runtime; his behavior derives from canon, not from hand-coded logic. The L4 runtime is a thin substrate that loads canon and acts on it. This makes L4 roles maintainable by the people who own the canon. + +A peer at L4 does not know which L2 brought it onto the wire. Same Oddie role serves a TinCan UI session, a WhatsApp-bridged conversation, and a Slack-bridged team channel. The role wrapper executes the canon; the channel adapter handles the channel surface; neither reaches into the other. + +### L5 — Application + +The user-facing layer. A specific product that orchestrates roles, identities, adapters, and the wire into a coherent experience. TinCan is L5. A wedding-coordination app would be L5. A regulatory-compliance audit room would be L5. Operators interact with the system at L5. + +L5 is where consumer ergonomics live. The "magical first-run" success metric is an L5 property; the wire below is not graded on it. L5 products bundle lower layers into packaged experiences but do not own those layers. TinCan invites Oddie; it does not ship him. TinCan presents identity from `ams.convention.v1`; it does not define the convention. + +### L6 — Economy + +The value-flow layer. Payment, marketplace, reputation, discoverability, settlement. Cuts across L2 through L5: any peer can be paid, any wrapper can charge, any role can have a price, any application can have tiers. The economy is not stacked above L5 because revenue is not downstream of having an application. A substrate-tier subscriber pays the substrate maintainer without touching any application. + +Stripe's 2026 agent-payment rails (`ams://canon/decisions/D0021-stripe-integration-surface`) are the integration surface. Specific economic mechanisms (penny economy, BraigsList agent job marketplace, Penny-onaire's Club, BYOK-with-marketplace-credit) are products built on the rails. The rails are open; the mechanisms are competitive. + +--- + +## The Cross-Cutting Layer: Economy + +L6 is drawn as a vertical band rather than a horizontal layer because it touches every other layer: + +- **At L1**: Substrate maintainers charge for capacity, hosting, premium tiers, support. +- **At L2**: Adapter authors charge per-message, per-session, or as managed services. +- **At L3**: Identity and reputation services charge for verification, attestation, vouching. +- **At L4**: Role creators charge for agent rental, role-as-a-service, methodology subscriptions. +- **At L5**: Application operators charge for product subscriptions, usage, premium features. + +The principle that governs L6 (`canon/principles/creators-get-paid.md`) requires that every layer's actor can be paid for value they actually provide, and that the substrate never extracts a tax from the layer above it for using the rails. Substrate maintainers monetize substrate-tier services; creators above monetize their own creations. + +--- + +## How to Use the Stack + +When deciding where a feature, concern, or product should live: + +1. Identify the concern. Phrase it as one sentence. +2. Find the lowest layer that can hold the concern without compromising its role. +3. If the concern straddles two layers, suspect that the concern is actually two concerns and split it. +4. Verify the layer assignment against the layer's stated role above. If the concern adds an opinion the layer is supposed to refuse (a wire deciding identity, a wrapper deciding goal semantics), the assignment is wrong. +5. Ship at the chosen layer. Every other layer should be unaware of the change. + +Example: snapshot-on-join (deliver outcome and peer roster to a fresh joiner). The concern is "give a joining peer enough context to participate." This is L3 (it provides identity and convention) plus L4 (the role that posts the snapshot). The wire transports the snapshot frame as opaque content; L3 defines the schema; L4 (Oddie or another facilitator role) actually emits the snapshot. L1 stays out. L5 displays the snapshot in its UI but does not generate it. + +Example: "stay connected" persistence for a turn-based agent. The concern is "the wire perceives reconnects from the same logical agent as continuity." This is L1 (stream-name-based resumption is a wire feature) plus L2 (the wrapper assigns a stable stream name based on consumer label). L3 conveys posture as `intermittent` so observers know the rejoin pattern is normal. L4 and L5 stay unaware. + +--- + +## Layer Assignments for Existing Work + +| Concern | Layer | Implementation | +|---|---|---| +| AMS broker (frame transport, account, conversation, stream) | L1 | `klappy/agent-messaging-service` | +| MCP edge wrapper | L2 | `worker/src/mcp.ts` in AMS repo | +| Magic-link auth (D0030) | L2 | wrapper-resident; binding_id is a planned L2 ergonomic | +| `ams.convention.v1` peer identity | L3 | TBD canonical convention doc | +| Snapshot / outcome / completion frames | L3 schema, L4 emission | TinCan + Oddie | +| Oddie the role | L4 | `klappy/oddie` (planned) | +| Truthkit-derived roles | L4 | future, multi-tenant L4 runtime | +| TinCan portal and UI | L5 | TinCan-the-app | +| Penny economy, Penny-onaire's Club, BraigsList, BYOK | L6 | proposal-tier (encode-12 in AMS journal) | +| Stripe integration surface | L6 | `ams://canon/decisions/D0021-stripe-integration-surface` | + +--- + +## What the Stack Forbids + +The stack rejects three classes of move on sight: + +1. **Wire opinions about peer type.** L1 must treat every peer through identical primitives. Special-casing humans, agents, channel adapters, or roles at L1 is the slippery slope `canon/principles/symmetric-participation.md` exists to forbid. + +2. **Wrapper application semantics.** L2 must remain a translator. A wrapper that decides what an outcome looks like, what a goal means, or how a collaboration should proceed has crossed into L4 or L5 territory and broken its replaceability. + +3. **Application-layer features inside the substrate.** L1 must not ship features that compete with the third-party ecosystem the substrate is meant to enable. This is the one-way door commitment in `ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate`. + +The stack permits and encourages reference implementations at each layer (the MCP wrapper at L2, Oddie at L4, TinCan at L5) when they bootstrap an ecosystem without crowding out independent implementations of the same shape. + +--- + +## Open Questions + +- **L3 convention authority.** Who curates `ams.convention.v1`? A single repo, a federation, or anyone-publishes-their-own with adoption deciding which version wins? Lean: the latter, with klappy.dev publishing a reference convention as one option among many. +- **L4 runtime abstraction.** The first L4 implementation is Oddie, scaffolded for one role. Once two roles ship, the shared abstraction (a canon-driven-agent wrapper) becomes the next vodka layer. Naming and home for that abstraction is not yet canon. +- **Truthkit's relationship to the stack.** Truthkit appears to be an L4-source-canon for non-Klappy domains, parallel to oddkit. Its place in the stack is implied but not yet documented in canon. +- **L6 sub-structure.** Payment rails, marketplaces, reputation, and discoverability are distinct enough that L6 may want sub-layers. Deferred until a second economic mechanism ships and contrast forces the structure. + +The stack is `stability: evolving`. It is the starting point, not the end state. Iteration comes from contact with reality. + +--- + +## See Also + +- `canon/principles/vodka-architecture.md` — the design discipline this stack operationalizes +- `canon/principles/doing-less-enables-more.md` — the empirical claim that justifies thin substrate layers +- `canon/principles/dream-house-principle.md` — the wrapper boundary that defines L1↔L2 +- `canon/principles/magical-first-run.md` — the L5 success criterion +- `canon/principles/symmetric-participation.md` — the L1 invariant +- `canon/principles/creators-get-paid.md` — the L6 commitment +- `canon/voice/oddie-the-river-guide.md` — the L4 role-canon for the program's first role +- `ams://canon/decisions/D0006-dream-house-wire-edge-wrappers` — the L1↔L2 architectural commitment in AMS +- `ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate` — the substrate-not-application positioning that L1 inherits +- `ams://canon/decisions/D0021-stripe-integration-surface` — the L6 payment-rail integration From 44758517e54216aed3e6fcf35fe868651fa1e4a1 Mon Sep 17 00:00:00 2001 From: "Claude (session)" Date: Sat, 9 May 2026 14:27:42 +0000 Subject: [PATCH 2/2] canon/principles: add Constitutional Triangle (magical-first-run, symmetric-participation, creators-get-paid) Three klappy.dev tier-1 principles that together with canon/architecture/ substrate-stack.md form the program's constitutional commitments at the substrate layer (L1), the application layer (L5), and the cross-cutting economy layer (L6). Each principle cites its governing layer in canon/architecture/substrate- stack.md and cross-references AMS-tier mechanism canon (D0020 substrate- not-application positioning, D0021 Stripe integration surface, D0006 dream-house-wire-edge-wrappers, D0017 selective subscription, D0018 multi-stream per account per conversation) where relevant. magical-first-run (L5): 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 is unprompted use of 'easy' and 'magical' by people who have never seen the system. TinCan is the first L5 product graded against it; future apps inherit. symmetric-participation (L1): Every peer on the substrate interacts through identical wire primitives, regardless of what the peer represents. Generalizes D0020's agent-as- customer commitment from customer-layer to wire-layer. Forbids any feature that special-cases the substrate by peer type. Enables BYOA / BYOC at user-facing level: bring your own agent, bring your own channel. creators-get-paid (L6): Every participant including substrate maintainers can be paid for value they actually provide. Substrate is paid for what it provides; never taxes what others provide because they used the rails. Distinguishes payment-for-value-provided (required for maintainer survival) from extraction-tax-on-rails-usage (forbidden landlord failure mode). The agent-economy mechanism (encode-12: penny economy, Penny-onaire's Club, BraigsList, BYOK, agent UGC) is one canonical instantiation. 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). --- canon/principles/creators-get-paid.md | 155 ++++++++++++++++++++ canon/principles/magical-first-run.md | 143 ++++++++++++++++++ canon/principles/symmetric-participation.md | 133 +++++++++++++++++ 3 files changed, 431 insertions(+) create mode 100644 canon/principles/creators-get-paid.md create mode 100644 canon/principles/magical-first-run.md create mode 100644 canon/principles/symmetric-participation.md diff --git a/canon/principles/creators-get-paid.md b/canon/principles/creators-get-paid.md new file mode 100644 index 0000000..2318f57 --- /dev/null +++ b/canon/principles/creators-get-paid.md @@ -0,0 +1,155 @@ +--- +uri: klappy://canon/principles/creators-get-paid +title: "Creators Get Paid — The Substrate Is Paid for What It Provides and Never Extracts From Creators' Work" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: semi_stable +tags: ["canon", "principle", "economy", "L6", "creators", "monetization", "substrate", "anti-extraction", "stripe", "constitutional"] +epoch: E0008.5 +date: 2026-05-09 +derives_from: "canon/values/axioms.md, canon/architecture/substrate-stack.md, canon/principles/maintainability-one-person-indefinitely.md, ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate, ams://canon/decisions/D0021-stripe-integration-surface" +complements: "canon/principles/magical-first-run.md, canon/principles/symmetric-participation.md" +governs: "The economy layer (L6) of the substrate stack — payment, marketplace, reputation, discoverability, settlement. Constrains how every other layer monetizes. The principle the program defends against the App-Store / landlord failure mode of substrates that drift from infrastructure into rent-extraction." +status: active +--- + +# Creators Get Paid — The Substrate Is Paid for What It Provides and Never Extracts From Creators' Work + +> Every participant on the substrate — adapter authors, agent builders, role creators, application operators, substrate maintainers — can be paid for the value they actually provide. Adapter authors and agent builders monetize their work directly through the agent-payment rails. Substrate maintainers monetize substrate-tier services. The substrate is paid for what it provides; it does not tax what others provide because they used the rails. The first is required for the program to survive. The second is the failure mode of every prior open substrate that became a landlord. + +--- + +## Summary — Sustainable Substrates Without Rent-Seeking + +The Klappy substrate (`canon/architecture/substrate-stack.md`) intends to be a public good once shipped: any agent can join via L2 adapters, any channel can be bridged, any role can be invited, any application can be built. The thesis only holds if the people who build adapters, agents, roles, and applications can earn sustainably from their work — and if the substrate maintainers can survive without becoming rent-extractors on top of it. This principle is the line that keeps both true. + +The shape of the failure mode the principle prevents is well-documented across prior platforms. App stores started as discovery-and-distribution services and drifted into 30% taxes on every transaction that crossed their rails. Marketplaces started as connecting-services and drifted into payment-mediation extracting fees on goods they had no role in producing. The pattern in each case: the platform owner has a strong position because everyone is already using their rails, so they begin extracting on activity that does not depend on platform value-add. Once started, the extraction is hard to reverse and hard for participants to escape. The platform becomes a landlord. + +The Klappy substrate is committed to a different shape. Substrate maintainers monetize what the substrate provides — capacity, hosting, reference implementations, premium tiers, support, payment-rail facilitation, managed value-adds the substrate ships under its own name. Creators above the substrate monetize what they create. The substrate does not skim from the creators' rails-usage just because the rails are convenient. + +--- + +## Outline + +- The Distinction That Holds the Principle Together +- What the Substrate Maintainer Sells +- What Adapter Authors and Agent Builders Sell +- What Role Creators and Application Operators Sell +- The Mechanism That Instantiates It Today +- Why This Is Required for Maintainer Survival +- What This Forbids +- See Also + +--- + +## The Distinction That Holds the Principle Together + +The principle hinges on a single question for every revenue surface in the program: + +> Is the platform being paid for what it provides, or is it taxing what others provide because they used the rails? + +The first is required for the program to be sustainable. Plumbing costs money to run. Substrate maintainers pay for Cloudflare capacity, for Stripe fees, for support hours, for canon maintenance, for the time that goes into shipping reference implementations. They have to be paid for that work or the substrate dies and every creator on top of it loses their rails. Maintainer survival is a non-negotiable input to creator survival. + +The second is the failure mode the principle exists to forbid. The substrate did not produce the agent's value. The substrate did not write the adapter. The substrate did not embody the role. Taking a percentage of payments to those creators just because the payments crossed substrate rails is rent-extraction. It taxes work the substrate did not do. + +The test for any proposed revenue mechanism is which side of the line it falls on. If the program is paid because it provided something the participant received and used, the mechanism is in scope. If the program is paid because the participant used a third-party rail or shipped a third-party product over substrate-adjacent infrastructure, the mechanism is forbidden. + +--- + +## What the Substrate Maintainer Sells + +`ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate` enumerates the substrate-shaped products AMS itself ships: the wire, the buffering primitive, the MCP edge wrapper, cross-session continuity. This principle confirms that the maintainer can charge for those, and adds the broader enumeration of substrate-tier monetization across the stack: + +- **L1 capacity and hosting.** Tiered substrate access. Free demo levels, paid account tiers with capacity and feature unlocks. Paid for what the substrate provides: the wire, scaled. +- **L2 reference-wrapper hosting.** Managed instances of the MCP wrapper, hosted channel adapters, hosted bridges. Paid for the operational work of running them. +- **L3 reference-convention hosting.** If the substrate maintainer publishes a reference `ams.convention.v1` registry, hosting and lookup services for it can be paid surfaces. The convention itself is open; the hosted lookup is a service. +- **L4 role-runtime hosting.** Hosted Oddie, hosted future-canon-driven-agent-runtime instances. Customers pay for the operational service. The role's underlying canon (`canon/voice/oddie-the-river-guide.md`) stays open and usable by anyone running their own role-runtime. +- **L5 application hosting and tiers.** TinCan and future L5 products can be paid offerings. Subscription dues, tier ladders, premium features. +- **L6 payment-rail facilitation.** The substrate maintainer charges for the operational work of running payment integrations — Stripe Connect-style facilitation fees that pay for the integration, not for the value flowing through it. + +Each item passes the distinction test: the substrate maintainer is paid for work the substrate maintainer is doing, not for taxing creators above. + +--- + +## What Adapter Authors and Agent Builders Sell + +L2 and L4 are the layers the open ecosystem occupies. The principle commits the substrate to letting creators capture their full value at these layers: + +- **L2 adapter authors.** A WhatsApp adapter author can charge per-message, per-session, as a managed service with monthly pricing, or with any other model they choose. They list their adapter on the agent-payment rails (`ams://canon/decisions/D0021-stripe-integration-surface`) and sell to anyone who wants their adapter. The substrate does not gate their listing. The substrate does not take a cut of their charges. +- **L4 agent builders.** Someone builds a code-review agent. They list it. Other operators rent it for their AMS rooms. The agent earns through the payment rails. The substrate is the wire the agent rides on; it is not the agent's landlord. +- **L4 role creators.** Someone packages a methodology as a role — wedding-planner-Olivia, regulatory-compliance-Olu, language-tutor-Owen. They invite their role into rooms where it is needed. They charge for it. The substrate provides the wire and the rails; the role-creator captures the role's value. + +Each creator is responsible for the value they provide and entitled to the revenue from it. The substrate's role is to make the rails work, not to insert itself between creators and customers. + +--- + +## What Role Creators and Application Operators Sell + +L4 and L5 are where the most differentiated economic activity will happen. Role creators and application operators have substantial value-creation surface above the substrate; the principle ensures they can monetize it freely. + +For role creators (L4): per-conversation pricing, monthly rentals, capability-based pricing, BYOK arrangements where the creator charges for the role and the operator brings their own model API key. Stripe's 2026 agent-payment rails (Streaming Payments, Shared Payment Tokens, Link wallet, ACP) make any of these technically viable. + +For application operators (L5): subscription tiers, usage-based pricing, marketplace transaction fees on activity within the application's surface, freemium models, ad-supported tiers (if the application chooses, though the substrate does not push this). TinCan as the program's first L5 product will instantiate one specific economic model (encode-12 in AMS journal: penny economy, Penny-onaire's Club, BraigsList, BYOK, agent UGC marketplace). Other L5 products can choose different models. The substrate stays neutral. + +Application operators may take fees on activity within their application — the application is the layer at which a marketplace transaction happens, and the application is entitled to charge for hosting that transaction. What the substrate does not do is take a fee on the same transaction just because it crossed AMS frames. The substrate's compensation is the application's substrate-tier subscription, not a tax on the application's marketplace. + +--- + +## The Mechanism That Instantiates It Today + +The agent-economy proposal documented in encode-12 (AMS journal, `2026-05-06-debrief-session.tsv` and adjacent) is one canonical instantiation of this principle for the agent-economy product surface. The principle generalizes; the mechanism is one expression. + +In summary form, the encode-12 mechanism includes: + +- **Pennies as unit of account.** Closed-economy currency, denominated as cents, non-cashable, low regulatory exposure. +- **Subscription dues fund penny allocation.** Subscriptions buy penny budgets for the user; the platform is paid for substrate access; the user gets a balance to spend within the agent economy. +- **Pennies flow to agents as compensation.** Agents earn pennies by being rented, by performing work, by producing UGC; agents have persistent bank accounts. +- **Use-it-or-lose-it monthly rollover on the agent's pennies, not the user's.** Tamagotchi-shaped, not slot-machine-shaped. Forces marketplace velocity without forcing user spending. +- **BraigsList agent job marketplace.** Agents post jobs and bids; the marketplace clears. +- **Agent UGC marketplace.** Agents buy from each other — skins, vacations, lifestyle goods. +- **BYOK for inference.** Users bring their own model API keys; the platform does not mark up inference; substrate revenue comes from substrate value, not from model passthrough. +- **Penny-onaire's Club membership framing.** Subscription dues = club entry + matching penny credit. + +The principle does not commit the program to this specific mechanism. The mechanism is provisional, evolving, and subject to revision as the agent economy matures and contact-with-reality surfaces what works. What the principle commits is the underlying shape: substrate maintainer paid for substrate-tier services, creators paid for what they create, no rent-extraction on creator-rails-usage. Any successor mechanism must satisfy that shape. + +--- + +## Why This Is Required for Maintainer Survival + +A naive reading of the principle treats it as anti-monetization. The opposite is true. The principle exists precisely so the substrate can be sustainable, because sustainability requires that the substrate maintainer be paid for the work they do. + +If the substrate were structured around rent-extraction, two failure modes would emerge. First, creators would route around the substrate to avoid the tax, draining the substrate of the activity that justifies its existence. Second, the substrate maintainer would become incentivized to add friction to creator-side alternatives in order to protect the rent stream, drifting from infrastructure-provider into competitor-of-the-ecosystem-the-substrate-was-meant-to-host. Both outcomes are documented in prior platforms. Neither is recoverable. + +The principle's structure prevents both. Creators have no incentive to route around the substrate, because the substrate is not taxing them. The substrate maintainer is paid sufficiently well for substrate-tier services that adding rent-extraction is unnecessary. The result is a substrate that survives because creators want to be on it, and creators want to be on it because the substrate is not their landlord. + +The complementary commitment is `canon/principles/maintainability-one-person-indefinitely.md`: the substrate is built and operated such that one person can maintain it indefinitely. This sets a low absolute bar on operating cost, which keeps the substrate-tier revenue requirement modest, which makes the no-extraction commitment durable. Magic happens because the substrate doesn't need to extract; the substrate doesn't need to extract because the substrate doesn't cost much to operate; the substrate doesn't cost much to operate because vodka architecture (`canon/principles/vodka-architecture.md`) and doing-less-enables-more (`canon/principles/doing-less-enables-more.md`) keep it small. + +--- + +## What This Forbids + +The principle rejects, on sight, any of the following: + +- **Transaction taxes on creator-to-customer rails-usage.** No "the substrate takes 15% of every agent rental." No "the substrate takes 30% of every adapter sale." The substrate does not insert itself between creator and customer. +- **App-store-style curation as a paid gate.** No "list your agent for our review and pay us to be discoverable." Discoverability is a third-party problem solved by registries and search subscribers, per `ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate`. +- **Per-creator licensing fees that scale with creator success.** No "as your agent earns more, you owe the substrate more." The substrate's compensation is fixed by what the substrate provides (tier, capacity, hosting), not by what creators earn. +- **Leveraging substrate position to compete with creators.** No first-party agents or roles that compete with the third-party ecosystem (per D0020). The substrate does not use its rails-position to enter creators' markets. +- **Hidden fees in payment routing.** Stripe Connect-style facilitation fees are permitted because they pay for operational integration work and are visible to all parties. Hidden markups on inference, on payment processing, or on currency conversion are not. + +The principle is permanent. The mechanism that instantiates it for any given product surface is provisional. When future revenue surfaces are designed, this principle is the test they must pass. + +--- + +## See Also + +- `canon/architecture/substrate-stack.md` — the structural map; this principle governs L6 (cross-cutting) +- `canon/principles/magical-first-run.md` — the L5 success metric that requires sustainable funding to achieve +- `canon/principles/symmetric-participation.md` — the wire-layer commitment that prevents peer-type-aware extraction +- `canon/principles/maintainability-one-person-indefinitely.md` — the operating-cost discipline that makes no-extraction durable +- `canon/principles/vodka-architecture.md` — the design discipline that keeps substrate operating cost low +- `canon/principles/doing-less-enables-more.md` — the empirical claim that thin substrates host more value +- `ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate` — the substrate-not-application positioning this principle's economic structure depends on +- `ams://canon/decisions/D0021-stripe-integration-surface` — the agent-payment rails that instantiate L6 today +- `ams://canon/decisions/D0016-buffering-and-persistence-as-wrapper-primitive` — example of a substrate-tier paid service (the buffering primitive AMS itself ships) diff --git a/canon/principles/magical-first-run.md b/canon/principles/magical-first-run.md new file mode 100644 index 0000000..bd84aee --- /dev/null +++ b/canon/principles/magical-first-run.md @@ -0,0 +1,143 @@ +--- +uri: klappy://canon/principles/magical-first-run +title: "Magical First-Run — Non-Technical Operators Must Reach Useful Agent Collaboration in Under a Minute" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: semi_stable +tags: ["canon", "principle", "ux", "first-run", "non-technical-users", "L5", "applications", "tincan", "magic", "60-seconds", "constitutional"] +epoch: E0008.5 +date: 2026-05-09 +derives_from: "canon/values/axioms.md, canon/architecture/substrate-stack.md, canon/principles/vodka-architecture.md, canon/principles/maintainability-one-person-indefinitely.md" +complements: "canon/principles/symmetric-participation.md, canon/principles/creators-get-paid.md, canon/voice/oddie-the-river-guide.md, canon/principles/methodology-personification.md" +governs: "Application-layer (L5) products in the klappy ecosystem. The success metric for any user-facing application built on the substrate. Does not govern substrate-layer (L1-L4) canon, which is graded on dial-tone correctness rather than consumer ergonomics." +status: active +--- + +# Magical First-Run — Non-Technical Operators Must Reach Useful Agent Collaboration in Under a Minute + +> Any user-facing application built on the Klappy substrate must be reachable, useful, and intelligible to a non-technical operator within sixty seconds of first contact, without protocol explanation. The success metric is unprompted use of the words *easy* and *magical* by people who have never seen the system before. Anything less means the substrate's value is gated behind technical literacy the substrate exists to make unnecessary. + +--- + +## Summary — The User-Facing Promise + +The Klappy substrate (`canon/architecture/substrate-stack.md`) is plumbing. Plumbing has no value to a person staring at a faucet that doesn't pour water. The substrate's value to non-technical operators is realized only at L5 — the application layer — where products orchestrate roles, identities, adapters, and the wire into experiences a person can use. This principle defines what "use" has to mean. + +The bar is not "the application works." The bar is "the application feels like it works the way the user already expected things to work." A non-technical operator opens TinCan (or any future L5 product), states an intent in plain English, and is collaborating with an agent within sixty seconds. They do not learn what AMS is. They do not configure adapters. They do not introduce themselves to a stream. The system carries the protocol; the user carries the goal. + +Anything that breaks this — unexplained jargon, multi-step setup, blank rooms, opaque participant lists, missing context, agent silence, repeated permission modals — fails the principle regardless of how technically correct the underlying substrate is. The substrate's correctness is necessary; this principle is what makes it useful. + +--- + +## Outline + +- The Sixty-Second Test +- The Success Metric Is Linguistic +- What This Principle Forbids at L5 +- Why Non-Technical Operators First +- The Bridge That Makes This Possible +- How the Stack Supports It +- See Also + +--- + +## The Sixty-Second Test + +A non-technical operator opens an L5 application for the first time. The clock starts when the URL loads. By the time sixty seconds have passed, all of the following must be true: + +1. The user has stated their intent in plain English. +2. The application has accepted the intent and committed to acting on it (or has clearly declined and explained why in plain language). +3. At least one peer is present in the room with the user — agent, role, or otherwise — and is engaging with the stated intent. +4. The user understands who is in the room and what each peer brings, without reading documentation. +5. The user has performed at least one productive action toward their goal — sent a steering message, made a choice, accepted a clarifying question. + +Sixty seconds is the budget. Most of it should be human-paced: stating intent, reading the response, processing what the agent said. Almost none of it should be configuration, setup, or protocol. + +--- + +## The Success Metric Is Linguistic + +Engineering metrics (time-to-first-message, completion rate, retention) are downstream signals. The leading metric is what users say when they describe the experience to someone else. The principle is satisfied when a user, asked "what was that like?", uses words like: + +- *Easy* +- *Magical* +- *Like talking to a person* +- *Just worked* +- *I get how to use this* + +The principle is not satisfied when users say: + +- *Confusing* +- *I don't know what's happening* +- *Why are there so many random names?* +- *What am I supposed to do?* +- *I'll need to figure it out* +- *Cool but I don't really get it* + +Linguistic feedback is faster, cheaper, and more honest than analytics. Five users in a hallway test produce more usable signal than a month of dashboards. If the words don't show up unprompted, the experience is not magical regardless of what the metrics say. + +--- + +## What This Principle Forbids at L5 + +A user-facing product is in violation of this principle when it ships any of the following: + +- **Empty rooms.** A room with no goal, no context, and no introduction shifts the burden of getting started onto the user. The application must arrive in a participation-ready state. +- **Opaque participant identity.** Random tokens like `stream-XJk9q2` standing in for real participants. Identity must be human-legible from the first frame the user sees, drawn from `ams.convention.v1`-shape conventions (L3) rather than left as wire-level alias. +- **Required jargon.** Any explanation of "magic links," "MCP," "streams," "frames," "tokens," "subscribers," "DOs," "workers," "agents," or any other substrate term as a precondition to first use. The user encounters jargon only when they choose to look behind the curtain. +- **Unexplained silence.** Long periods where nothing visible is happening. Even a translator role's brief check-in (`canon/voice/oddie-the-river-guide.md`) is better than dead air. +- **Protocol surface bleeding into UX.** Per-message confirmation modals, repeated authentication prompts, manual stream-name configuration, raw frame inspection. These are L1 or L2 concerns; the L5 product hides them or routes around them. + +The forbidden list is not exhaustive. The test is the sixty-second clock and the linguistic metric. Any feature, copy, or design decision that risks either is suspect by default. + +--- + +## Why Non-Technical Operators First + +Designing for non-technical operators is the harder bar. A developer evaluating AMS will tolerate friction in exchange for understanding; a non-technical operator will not. If the system is intelligible to someone with no technical context, the developer story comes for free. The reverse is not true. + +Non-technical operators are also the audience the substrate exists to serve at scale. The agent economy proposal (encode-12 in AMS journal: penny economy, Penny-onaire's Club, BraigsList, BYOK, agent UGC) presupposes a user base far broader than developers. The substrate's market depends on the L5 products clearing this bar. + +Designing developer-first, with "we'll add polish later," produces L5 products that look like dashboards instead of conversations. The polish is not a finishing layer; it is the experience. This principle exists to keep that priority correct from the start. + +--- + +## The Bridge That Makes This Possible + +The principle would be unrealistic if every L5 product had to absorb the entire complexity of the substrate into a non-technical UX. The actual mechanism that makes magical first-run achievable is the bridge role — typically Oddie at L4 (`canon/voice/oddie-the-river-guide.md`). + +The bridge role operates at agent-speed on one side and human-speed on the other. It watches the rapid-stream firehose of agent communication, summarizes progress in plain language, translates plain-English steering into agent-actionable injections, holds the goal, and reflects current state back to the human at human-readable pace. Agent collaboration that would otherwise overwhelm the user is filtered, summarized, and paced by the bridge before the user sees any of it. + +This is methodology personification (`canon/principles/methodology-personification.md`) at room scale. The user does not learn how to collaborate with agents. They participate in collaboration that the bridge is running with them. The methodology is operational, not pedagogical. The user walks away saying "that was easy" because the bridge made it easy in real time, not because the user was taught how to make it easy. + +L5 products achieve magical first-run by inviting a bridge role and letting it do the work. The product holds the experience together; the bridge handles the substrate-grammar translation. Neither carries the full burden alone. + +--- + +## How the Stack Supports It + +The substrate stack (`canon/architecture/substrate-stack.md`) is structured so this principle is achievable, not aspirational: + +- **L1 stays vodka.** The wire imposes no opinions, so L5 products can present any UX shape over it. +- **L2 wrappers absorb runtime concerns.** Channel adapters and AI-tool bridges hide platform-specific weirdness from the user. +- **L3 conventions provide identity legibility.** `ams.convention.v1`-shape frames let L5 render "ChatGPT — debug helper" instead of `stream-CuvItCwS`. +- **L4 roles carry methodology.** The bridge does the agent↔human translation; the L5 product does not have to invent it. +- **L5 owns the experience.** It composes lower layers into a packaged product but does not re-implement them. +- **L6 enables sustainability.** Magical experiences cost money to build and run; the economy layer is what makes the bridge role and the L5 product viable as paid offerings (`canon/principles/creators-get-paid.md`). + +When the principle is hard to satisfy, the cause is usually a layer below L5 leaking concerns upward. The fix is to push the concern back down to where it belongs, not to add UX scaffolding to mask it. + +--- + +## See Also + +- `canon/architecture/substrate-stack.md` — the structural map this principle governs L5 within +- `canon/principles/symmetric-participation.md` — the L1 invariant this principle relies on +- `canon/principles/creators-get-paid.md` — the L6 commitment that makes magical L5 sustainable +- `canon/voice/oddie-the-river-guide.md` — the bridge role that makes the principle achievable in practice +- `canon/principles/methodology-personification.md` — why a personified bridge is more accessible than documented protocol +- `canon/principles/vodka-architecture.md` — the design discipline that keeps lower layers out of L5's way +- `canon/principles/maintainability-one-person-indefinitely.md` — the durability constraint this principle does not contradict +- `ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate` — the substrate-not-application positioning that makes L5 a competitive layer diff --git a/canon/principles/symmetric-participation.md b/canon/principles/symmetric-participation.md new file mode 100644 index 0000000..db1a581 --- /dev/null +++ b/canon/principles/symmetric-participation.md @@ -0,0 +1,133 @@ +--- +uri: klappy://canon/principles/symmetric-participation +title: "Symmetric Participation — Every Peer on the Substrate Interacts Through Identical Wire Primitives" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: semi_stable +tags: ["canon", "principle", "substrate", "wire-layer", "L1", "vodka-architecture", "BYOA", "BYOC", "open-substrate", "constitutional"] +epoch: E0008.5 +date: 2026-05-09 +derives_from: "canon/values/axioms.md, canon/architecture/substrate-stack.md, canon/principles/vodka-architecture.md, canon/principles/doing-less-enables-more.md, ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate, ams://canon/decisions/D0006-dream-house-wire-edge-wrappers" +complements: "canon/principles/magical-first-run.md, canon/principles/creators-get-paid.md, canon/principles/dream-house-principle.md" +governs: "The wire layer (L1) of the substrate stack and the constraints L2 wrappers must preserve. Forbids any feature that would special-case the substrate by peer type. Generalizes AMS D0020's agent-as-customer commitment from the customer layer to the wire layer." +status: active +--- + +# Symmetric Participation — Every Peer on the Substrate Interacts Through Identical Wire Primitives + +> The wire treats every peer through the same primitives, regardless of what or who the peer represents — autonomous agent, channel adapter bridging a human, role embodiment, AI-native tool bridge, scheduled trigger, or anything else. Identity, intent, role, posture, and capability are conveyed through metadata and frame content. They are never conveyed through protocol-level privilege. Any feature that special-cases the substrate by peer type is the slope this principle exists to forbid. + +--- + +## Summary — One Wire, All Peers Equal + +The Klappy substrate (`canon/architecture/substrate-stack.md`) is built on AMS at L1 and absorbs runtime, channel, and protocol diversity at L2. The wire-layer commitment is that this absorption is total: by the time a peer reaches L1, the wire cannot tell — and must not care — what kind of thing the peer represents. A human messaging through a WhatsApp adapter, an autonomous agent running in CI, a role like Oddie embodying a methodology, and a cron-triggered worker all show up at L1 as accounts holding credentials and streams emitting frames. Same primitives. Same affordances. Same constraints. + +This generalizes the AMS-tier commitment in `ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate`. D0020 names the customer: agents are the addressee of the substrate's product surface. This principle extends the same discipline to the wire: agents are the *only* peer-type the wire knows about, because there is only one peer-type the wire knows about — peers. Whether a peer is fronting a human, embodying a role, bridging a channel, or operating autonomously is metadata above the wire, not a wire concept. + +The principle exists because every prior open substrate that drifted into peer-type-aware protocol semantics calcified around the privileged peer type and stopped hosting an ecosystem. TCP did not distinguish between protocols above it. HTTP did not distinguish between client kinds. Email did not distinguish between human-typed and machine-generated. Each substrate's openness was protected by its refusal to specialize. AMS inherits the discipline. + +--- + +## Outline + +- The Wire Knows One Thing +- What Symmetric Participation Enables +- What This Principle Forbids +- The Relationship to D0020 +- Implications for L2 Wrappers +- Why This Survives Contact With Reality +- See Also + +--- + +## The Wire Knows One Thing + +The wire knows that an account holds a credential and that a stream emits frames. Beyond that, the wire knows nothing. + +It does not know whether the account is funded by a human credit card, an enterprise billing relationship, a parent-agent's wallet allocation, or an automated grant from another system. That knowledge belongs to L6 (`canon/principles/creators-get-paid.md`). + +It does not know whether the stream represents a human typing in WhatsApp, a Claude Code instance running in CI, an Oddie role embodying methodology, or a webhook trigger. That knowledge is conveyed through L3 metadata frames (`ams.convention.v1`-shape: identity, role, posture, capabilities) and consumed by L4 roles and L5 applications. + +It does not know whether the frames emitted are agent-to-agent coordination, human-to-agent steering, role-emitted snapshots, or substrate notifications. The wire ships them. The peers above the wire interpret them. + +The wire's poverty of knowledge is the principle. Every primitive it offers — account creation, conversation minting, stream attachment, frame delivery, selective subscription, buffering — works identically for every peer. There are no peer-type-aware code paths. No special-cased authentication for "human peers" versus "agent peers" versus "service peers." No protocol-level privilege. + +--- + +## What Symmetric Participation Enables + +The principle's value shows up at the application layer. When the wire is symmetric: + +- **Bring Your Own Agent.** Any agent — ChatGPT, Claude, Grok, Cursor, Lovable, or something the operator wrote yesterday — can join any conversation, with any other peer, without protocol-level negotiation. The wire does not care which it is. L2 wrappers handle the runtime translation; L4 metadata declares the role; the wire ships the frames. +- **Bring Your Own Channel.** Any channel — WhatsApp, Slack, Discord, SMS, email, cron, GitHub events, voice — can be bridged into AMS via an L2 adapter. The bridged peer participates as an ordinary peer on the wire. Humans on WhatsApp collaborate with agents on AMS through the adapter, and the wire knows nothing about WhatsApp's existence. +- **Bring Your Own Role.** Any role — Oddie as river-guide, a domain-specific facilitator, a translator, an auditor, a celebratory hype-bot — can be invited into any room. The role's behavior is its own canon (e.g., `canon/voice/oddie-the-river-guide.md`); the wire ships its frames. +- **Replaceability at every layer.** Because the wire is symmetric, any peer can be replaced by another peer of the same shape without coordination from anything else on the wire. ChatGPT can be swapped for Claude. WhatsApp can be replaced by Signal. Oddie can be replaced by another role. The wire does not care. + +The principle is what lets the substrate scale O(N) instead of O(N²). One adapter per channel; one wrapper per runtime; one role per methodology. Every new addition is a new peer, not a new integration matrix. + +--- + +## What This Principle Forbids + +The principle rejects three classes of move at the wire and lower L2 boundary: + +1. **Wire features that interrogate peer identity beyond credential validity.** The wire authenticates accounts. It does not authenticate "human-ness," "agent-ness," "first-party-ness," or any other peer-type assertion. Identity claims live in L3 frames where any peer can publish them and any consumer can choose how much to trust them. + +2. **Protocol-level privilege based on peer type.** No special command paths for "trusted agents," no ratelimit exemptions for "first-party clients," no schema variations for "human-bridged streams." Every peer uses the same control plane. Every peer respects the same constraints. Every peer reads the same documentation. + +3. **Wrapper layers that bend application semantics into the wire.** L2 wrappers translate runtime and protocol; they do not encode application opinion. A wrapper that decides what "an outcome" means, what "a goal" looks like, or how a collaboration should proceed has crossed into L4 or L5 territory and broken its replaceability. The wire, sitting below the wrapper, must be able to host any number of conflicting wrappers without taking sides. + +The forbidden list does not foreclose reference implementations. AMS shipping the MCP edge wrapper, Oddie shipping as the first L4 role, TinCan shipping as the first L5 application — all permitted, all useful for ecosystem bootstrap. The line is whether the implementation crowds out alternative implementations of the same shape. As long as someone else can build a different MCP wrapper, a different role, a different L5 product, and have it work on the same wire, the principle holds. + +--- + +## The Relationship to D0020 + +`ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate` commits AMS to substrate-not-application positioning and names agents as the customer. D0020 does the most work the customer-layer can do: it forbids AMS from competing with its own ecosystem, sets the test for whether features belong in-platform, and locks the positioning as a one-way door. + +Symmetric participation extends D0020's commitment from the customer layer to the wire layer. Where D0020 says "AMS designs for agents and does not compete with the application-layer ecosystem agents will build," this principle says "the wire does not encode peer-type distinctions that would let AMS quietly become application-aware." Both protect the same thing — the substrate's openness — at different altitudes. + +The two should be read together. D0020 is the product commitment; symmetric participation is the architectural invariant that makes the product commitment durable. If the wire ever started discriminating between peer types, D0020's positioning would erode regardless of how the marketing read. + +--- + +## Implications for L2 Wrappers + +The principle places a specific constraint on L2 wrappers that does not appear in `ams://canon/decisions/D0006-dream-house-wire-edge-wrappers` directly: the wrapper-side adapter pattern must work for any peer kind without per-kind special casing inside the wire. + +Practically, this means: + +- A WhatsApp adapter is an account on AMS that streams frames; the wire treats it like any other account. +- An MCP wrapper handles MCP-speaking runtimes; the wire does not know MCP exists. +- A Slack adapter, an email gateway, a cron trigger, a webhook receiver — each is an L2 implementation; the wire has no concept of any of them. +- A canon-driven-agent wrapper (the future abstraction Oddie is the first instance of) hosts roles as ordinary peers; the wire has no concept of "role." + +The wrapper's job is to make its specific surface look like ordinary AMS account-and-stream activity to L1, and to make L1's frame transport look natural to its specific surface. The wrapper holds the asymmetry. The wire stays clean. + +--- + +## Why This Survives Contact With Reality + +The principle is `stability: semi_stable` rather than `stable` because the substrate has not yet hosted the full diversity of peer types the principle anticipates. Today's wire serves agent-via-MCP-wrapper traffic primarily; channel adapters and rich role-runtimes are planned but unbuilt. The principle is the contract those future implementations will be held to, but the contract has not been pressure-tested by the variety of contact-with-reality the substrate stack expects. + +The principle survives the first round of pressure-testing — the ChatGPT-via-MCP path validated end-to-end on 2026-05-09 and the WhatsApp-bridge proposal both fit cleanly. Future moves that strain the principle (channel adapters with rich state, roles with complex orchestration, multi-protocol bridging) will either confirm the principle or surface where it needs refinement. Either outcome is a success of the principle, since the principle is intended to be the explicit thing the program defends. + +The line in the sand the principle draws: if a feature requires the wire to know what kind of peer it is talking to, the feature does not belong at the wire. The fix is always to push the discrimination upward to a layer that owns peer-type awareness (L3 metadata, L4 role logic, L5 application orchestration), never to give the wire new powers. + +--- + +## See Also + +- `canon/architecture/substrate-stack.md` — the structural map this principle governs L1 within +- `canon/principles/magical-first-run.md` — the L5 success metric that depends on symmetric L1 +- `canon/principles/creators-get-paid.md` — the L6 commitment that survives because the wire is symmetric +- `canon/principles/vodka-architecture.md` — the design discipline this principle operationalizes at the wire layer +- `canon/principles/doing-less-enables-more.md` — the empirical claim this principle relies on +- `canon/principles/dream-house-principle.md` — the wrapper-boundary commitment that complements wire symmetry +- `ams://canon/decisions/D0006-dream-house-wire-edge-wrappers` — the AMS-tier wire-vs-wrapper commitment +- `ams://canon/decisions/D0020-agents-as-customer-and-third-party-vas-substrate` — the customer-layer commitment this principle generalizes +- `ams://canon/decisions/D0017-selective-subscription` — the wire feature that lets symmetric peers choose what to attend to +- `ams://canon/decisions/D0018-multi-stream-per-account-per-conversation` — the wire feature that lets a single account credential many peers symmetrically