# RAPP/1 Reference Vault - all notes Source: https://microsoft.github.io/aibast-agents-library/docs/vault/ . Protocol notes are pinned to RAPP/1 upstream commit 0b24e7d60786d39d97265338add9ca784bf5a7ab (MIT; see NOTICE.md). ======================================================================== FILE: README.md ======================================================================== --- title: Welcome status: published hook: What this vault is, who it is for, and where to start. source: docs/rapp-guide.html; upstream RAPP/1 specification --- # Welcome **This vault is the reference half of the RAPP production guide.** The [production guide](../rapp-guide.html) tells you what to do at each of the 14 steps. This vault tells you more about each step, and explains the **RAPP/1 protocol** underneath it: how an agent is identified, recorded, packaged and moved. ## Who it is for - **Business leads** who run the 14-step process and want each step in depth. - **Builders** who write and ship single-file agents. - **Implementers** who want to read or write RAPP/1 records in another language. [[Reading Paths]] gives each of them a route through the notes. ## What is inside - **[[Production Guide Overview|Production Guide]]**: one note per guide step. - **[[Protocol at a Glance|Protocol]]**: the RAPP/1 specification in plain language. - **Operations**: release, deployment and work records in [[RAPP CICD]], [[RAPP Deploy]] and [[RAPP Work]]. - **Building**: the agent file in [[The Agent Contract]], the Brainstem in [[The Brainstem Kernel]], and pinning in [[Distros and Pinning]]. - **Reference**: terms in [[Glossary]], failures in [[Failure Atlas]], and sources in [[Sources and Provenance]]. ## Ways to read it - **In the browser:** search, backlinks and a graph of every link. - **In Obsidian:** download the vault and open the folder. See [[How to Use This Vault]]. - **With an AI tool:** point it at `llms.txt` or `llms-full.txt` in this folder. ## Where the content comes from Protocol notes restate the upstream RAPP/1 specification at a pinned commit. See [[Sources and Provenance]] and the [Notice](NOTICE.md). ======================================================================== FILE: _index.md ======================================================================== --- title: Index status: published hook: Every note in the vault, grouped by section. source: generated by tools/build_rapp1_vault.py --- # Index Every note in the RAPP/1 reference vault, grouped by section. Start with [[Welcome]] or [[Reading Paths]]. ## Start Here - [[How to Use This Vault]] - How do I read, search, download and share this vault? - [[Reading Paths]] - Which notes should I read, in what order, for my role? ## Production Guide - [[Production Guide Overview]] - What the 14-step RAPP production process is, who runs each step, and where the six human quality gates sit. - [[Step 01 Discovery Call]] - How to run the discovery call whose transcript becomes the foundation for every later step. - [[Step 02 Transcript Analysis]] - How the transcript is turned into structured project JSON and audited at Quality Gate 1. - [[Step 03 Generate MVP Poke]] - What an MVP poke is, what goes in it, and how it is sent to the customer before any code is written. - [[Step 04 Customer Validation]] - How the customer signs off on the MVP scope at Quality Gate 2, and what to do for each possible answer. - [[Step 05 Generate Agent Code]] - How the locked MVP becomes Python agent files that follow the BasicAgent pattern. - [[Step 06 Code Quality Review]] - What a reviewer checks in generated agent code at Quality Gate 3 before it is deployed. - [[Step 07 Deploy Prototype]] - How reviewed agents get running locally, in Azure, and in Copilot Studio, and how to verify the deployment. - [[Step 08 Demo Review]] - How the customer first sees the working prototype, and how Quality Gate 4 decides what happens next. - [[Step 09 Generate Video Demo]] - How to turn the approved prototype into a produced, narrated demo for executives. - [[Step 10 Final Demo Review]] - How the customer approves the produced video demo for executive sharing at Quality Gate 5. - [[Step 11 Production Planning]] - How the prototype's requirements for security, compliance, and rollout are defined before production. - [[Step 12 Security Sign-off]] - How IT, Security, and Compliance formally approve production deployment at Quality Gate 6. - [[Step 13 Production Deployment]] - How the approved system is deployed to the customer's environment and rolled out to pilot users. - [[Step 14 Post-Deployment Review]] - How the pilot is measured against the MVP targets and how Phase 2 is planned. ## Protocol - [[Canonicalization]] - How does rapp/1 turn any JSON value into one exact byte string? - [[Conformance Classes]] - What does an implementation have to do to claim it conforms to rapp/1, and what extra rules apply to the Grail kernel and production operations? - [[Content Addressing]] - How does rapp/1 hash things, and why is every hash tagged with a space? - [[Identity and the Rappid]] - What is a rappid, how is it minted, and when may it ever change? - [[Protocol at a Glance]] - What is rapp/1, and what does it promise in one page? - [[Protocol Layers]] - How is rapp/1 split into layers, and what may each layer do? - [[Security Considerations]] - Which threats does rapp/1 defend against, which ones do hashes alone not stop, and what control covers each? - [[The Egg]] - How does rapp/1 package a whole agent, application, or space so anyone can verify it before using it? - [[The Frame]] - What is a rapp/1 frame, what are its eleven fields, and how is it verified? - [[The Registry]] - What is the estate registry, why is it the root of trust, and how does a consumer know it is genuine and current? - [[The Wire]] - How do RAPP systems talk to each other, and what exactly does POST /chat accept and return? - [[Trust and Signatures]] - What does a rapp/1 signature prove, how is it checked, and how do key rotation and revocation work? - [[Versioning and Evolution]] - How does rapp/1 change over time without breaking verification of anything already published? ## Operations - [[RAPP CICD]] - How does one exact AI release candidate earn promotion toward production under rapp/1? - [[RAPP Deploy]] - How does a qualified rapp/1 release reach users safely and stay provably healthy afterward? - [[RAPP Work]] - How does rapp/1 bind a work organization to its catalog, releases, migrations, and rollback targets without granting hidden authority? ## Building - [[Conformance and Drift]] - How do you prove an implementation conforms to rapp/1, and how do you find and fix drift in real artifacts? - [[Distros and Pinning]] - How does this library ship the Brainstem kernel pinned by a species contract and drift-ledgered, with every difference recorded in `rapp/KERNEL-DRIFT.md`, and its own catalog around it? - [[Implementing the Protocol]] - In what order should you build a rapp/1 implementation, and how do you know it is done? - [[The Agent Contract]] - What exactly must a Brainstem agent file look like, and how does it reach the user through POST /chat? - [[The Brainstem Kernel]] - What is the Brainstem kernel this library ships, and what does it guarantee to every agent and host? ## ms-rapp-1 - [[Microsoft Foundry]] - How is ms-rapp/1 used in Microsoft Foundry, and what does a Foundry agent see? - [[ms-rapp-1 Overview]] - What is ms-rapp/1, and how does it stay backward compatible with rapp/1 and the Brainstem? - [[One Concept Across the Stack]] - How does one Step file show up in Copilot Studio, Microsoft 365 Copilot, Foundry, the Agent Framework and the Agents SDK? - [[RAPP Runtime]] - What is RAPP Runtime, and how does each of its pieces map to the Brainstem? - [[Run Receipts and Change Control]] - How does ms-rapp/1 keep an AI step auditable, and how does a new Step get into production? - [[Steps]] - What does a Step file look like, and why does it load unchanged in a Brainstem? ## Reference - [[Failure Atlas]] - When a frame is refused, which check failed and what usually caused it? - [[Glossary]] - What does each rapp/1 term mean, in plain words? - [[Sources and Provenance]] - Where does this vault's protocol content come from, and which text is authoritative? ======================================================================== FILE: NOTICE.md ======================================================================== --- title: Notice status: published hook: Where the vault's content and viewer come from, and the licences that apply. source: upstream licence files --- # Notice **The specification stays the authority.** The Protocol and Operations notes in this vault are a plain-language expansion of the RAPP/1 specification. Each one names the section it restates and the upstream commit it was written against. Where a note and the specification differ, the specification wins. ## Upstream specification - **Name:** RAPP/1 specification - **Repository:** https://github.com/kody-w/rapp-1 - **Pinned commit:** `0b24e7d60786d39d97265338add9ca784bf5a7ab` - **Licence:** MIT ## Vault viewer The browser viewer (`vault.js`, `vault.css`) is adapted from the RAPP vault viewer by the same author, provided to this repository under the MIT licence. ## Markdown renderer `marked.min.js` is marked 12.0.2, MIT licence. Its notice is in `vendor/marked-LICENSE.txt`. ## MIT licence (upstream specification and viewer) ```text MIT License Copyright (c) 2025-2026 Kody Wildfeuer Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` ======================================================================== FILE: Start Here/How to Use This Vault.md ======================================================================== --- title: How to Use This Vault section: Start Here status: published hook: How do I read, search, download and share this vault? source: "docs/rapp-guide.html" --- # How to Use This Vault This **vault** is a set of linked notes. It expands the RAPP production guide and the rapp/1 protocol into short, readable pages. You can read it in your browser, or download it and open it in Obsidian. ## Reading in the browser Each note is one page. Links between notes are underlined. - **Search** — find any note by title or text. - **Graph** — see how notes connect to each other. - **Backlinks** — at the bottom of a note, see which other notes link to it. ### Keyboard keys | Key | What it does | |---|---| | `j` / `k` | move to the next / previous note | | `/` | open search | | `g` then `g` | open the graph | | `g` then `i` | go to the index | | `r` | open a random note | | `m` | turn reading mode on or off | | `?` | show or hide the keyboard hint | ## Where to start - New here? Read [[Welcome]]. - Want a route through the notes? Pick one in [[Reading Paths]]. - Need a word explained? Use the [[Glossary]]. ## Downloading the vault You can take the whole vault with you as a real Obsidian vault. 1. Press the **Download vault** button at the top of the page. 2. You get `rapp1-vault.zip`. 3. Unzip it. 4. In Obsidian, choose **Open folder as vault** and pick the unzipped folder. Every `[[wikilink]]` works in Obsidian, because each note file is named exactly after its title. ## How each note is built - A short **plain-language lead** at the top. - Sections with clear headings. Technical detail sits lower down. - Exact identifiers stay in `code` style, for example `rapp/1`. - A **Related** list at the end. Each note's frontmatter names its source. See [[Sources and Provenance]]. ## For AI tools AI tools can read the vault directly: - `llms.txt` — a short index of the notes. - `llms-full.txt` — the full text of every note in one file. The **Plain text** button at the top opens `llms-full.txt`. Point an assistant at either file to ground its answers in this vault. ## Related - [[Welcome]] - [[Reading Paths]] - [[Glossary]] - [[Sources and Provenance]] - [[Production Guide Overview]] ======================================================================== FILE: Start Here/Reading Paths.md ======================================================================== --- title: Reading Paths section: Start Here status: published hook: Which notes should I read, in what order, for my role? source: "docs/rapp-guide.html" --- # Reading Paths A **reading path** is a short, ordered list of notes for one role. Pick the path that matches your job. Read top to bottom. You can leave the path at any point and follow links. ## Pick your path | You are | You want to | Path | |---|---|---| | **Business lead** | understand the process and what each step delivers | Business lead | | **Builder** | write an agent and get it running | Builder | | **Implementer** | build software that speaks rapp/1 | Implementer | ## Business lead For people who sponsor, plan or review agent projects. No code required. 1. [[Production Guide Overview]] — the 14 steps from discovery call to post-deployment review. 2. The steps, in order — start with [[Step 01 Discovery Call]] and continue through [[Step 14 Post-Deployment Review]]. 3. [[Protocol at a Glance]] — a one-page view of what sits underneath. ## Builder For people who write and ship agents. 1. [[The Agent Contract]] — what a single agent file must provide. 2. [[The Frame]] — how each event is recorded. 3. [[The Egg]] — how agents and rapplications are packaged to move between machines. 4. [[RAPP Deploy]] — how a release reaches users. ## Implementer For engineers building a producer, consumer or mirror. Read in this order; each note builds on the one before. 1. [[Protocol at a Glance]] 2. [[Canonicalization]] 3. [[Content Addressing]] 4. [[Identity and the Rappid]] 5. [[The Frame]] 6. [[The Wire]] 7. [[The Egg]] 8. [[Conformance Classes]] 9. [[Implementing the Protocol]] Keep the [[Glossary]] and [[Failure Atlas]] open beside you. ## Tips - Unsure about a word? Check the [[Glossary]]. - Want to know where a claim comes from? See [[Sources and Provenance]]. - Lost? Go back to [[How to Use This Vault]]. ## Related - [[Welcome]] - [[How to Use This Vault]] - [[Production Guide Overview]] - [[Protocol at a Glance]] - [[Implementing the Protocol]] ======================================================================== FILE: Production Guide/Production Guide Overview.md ======================================================================== --- title: Production Guide Overview section: Production Guide status: published hook: What the 14-step RAPP production process is, who runs each step, and where the six human quality gates sit. source: "docs/rapp-guide.html#overview; docs/rapp-guide.html#architecture; docs/rapp-guide.html#principles; SPEC.md §1.1, §8, §11.1, §11.2" upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Production Guide Overview The **Rapid Agent Prototype Pattern (RAPP)** turns a customer conversation into a working AI agent in days, not months. AI does the heavy lifting. People apply judgment at **six quality gates**. This note maps the 14 steps and shows where the rapp/1 protocol supports them. ## The idea in one line - **Automation does the volume work:** extracting project data, drafting summaries, generating agent code. - **Humans keep the judgment:** is this the right problem, is the code safe, is it ready to show? Each gate takes 15-60 minutes of human time. It prevents days or weeks of wasted work. ## The 14 steps | Step | Type | Duration | Owner | |---|---|---|---| | [[Step 01 Discovery Call\|1. Discovery Call]] | Manual | 30-60 minutes | Field Team | | [[Step 02 Transcript Analysis\|2. Transcript Analysis]] | Audit (Gate 1) | 15 minutes | Delivery Team | | [[Step 03 Generate MVP Poke\|3. Generate MVP Poke]] | Manual | 1-2 hours (manual) | Delivery Team | | [[Step 04 Customer Validation\|4. Customer Validation]] | Audit (Gate 2) | 1-2 days | Field Team | | [[Step 05 Generate Agent Code\|5. Generate Agent Code]] | Manual | Days-Weeks | Technical Team | | [[Step 06 Code Quality Review\|6. Code Quality Review]] | Audit (Gate 3) | 30-60 minutes | Technical Team | | [[Step 07 Deploy Prototype\|7. Deploy Prototype]] | Manual | 1-2 hours | Technical Team | | [[Step 08 Demo Review\|8. Demo Review]] | Audit (Gate 4) | 30 min | Delivery Lead | | [[Step 09 Generate Video Demo\|9. Generate Video Demo]] | Manual | 3-4 hours (manual) | Delivery Team | | [[Step 10 Final Demo Review\|10. Final Demo Review]] | Audit (Gate 5) | 30-60 minutes (review call with customer) | Delivery Lead | | [[Step 11 Production Planning\|11. Production Planning]] | Manual | 3-7 days (meetings + documentation) | Technical Team | | [[Step 12 Security Sign-off\|12. Security and Compliance Sign-off]] | Audit (Gate 6) | 1-3 weeks (review process, pen testing, compliance audit) | Customer IT and Security | | [[Step 13 Production Deployment\|13. Production Deployment]] | Manual | 1 day | Technical Team | | [[Step 14 Post-Deployment Review\|14. Post-Deployment Review]] | Audit | Ongoing | Success Team | Durations and owners follow the guide's overview table. Some step sections in the guide give different times; each step note carries its section's figures. ## The six quality gates 1. **Transcript Audit** — did we extract the right problem? 2. **Customer MVP Validation** — does the customer agree this is the MVP? 3. **Code Quality Review** — are the generated agents secure and correct? 4. **Demo Review** — is this ready to show the customer? 5. **Final Demo Review** — is this feedback in scope, or scope creep? 6. **Security and Compliance Sign-off** — will IT, Security and Compliance let this go live? ## Why the order matters: risk elimination The biggest risk is spending six months on a problem nobody cares about. RAPP puts customer checkpoints first: - The **MVP poke** (Step 3) gets feedback before real work begins. - By Step 6, code exists with **locked scope** and customer sign-off. - The working demo (Step 8) is the second major checkpoint. If the customer says no, you have spent days, not months. ## The four architecture layers | Layer | Responsibility | Technology | |---|---|---| | Interface | User channels | M365 Copilot, Teams, Web, Mobile, Voice | | Orchestration | Conversation, routing, history | Copilot Studio + Power Automate | | Intelligence | Agent execution, tool calling | RAPP Brainstem locally, or the Azure Function App | | Storage | Agent code, memory, workflows | Azure File Storage | Agents **hot-load**. Locally the Brainstem re-reads its agents folder on every request. In Azure, agents in the file share's `agents/` directory refresh on a five-minute cache. ## How rapp/1 underpins the process The guide describes the delivery process. The upstream RAPP/1 specification defines the bytes the delivered agents speak. - **One wire.** Every interaction rides `POST /chat` or a signed append-only frame. New capability is a new agent behind `/chat`, never a sibling REST route. See [[The Wire]]. - **Five layers.** Address, identity, wire, frame and egg each name one canonical form. A higher layer must not redefine a lower one. See [[Protocol Layers]]. - **Unchanged kernel.** New behavior lives outside the pinned Grail kernel. See [[The Brainstem Kernel]] and [[Distros and Pinning]]. - **Production operations.** The upstream specification defines two operational profiles: `rapp-cicd/1` (immutable release capsules, qualification evidence, promotion, rollback) and `rapp-deploy/1` (isolated lineages, progressive exposure, quarantine, exact rollback). See [[RAPP CICD]] and [[RAPP Deploy]]. Guide section: [Framework Overview in the production guide](../rapp-guide.html#overview) ## Related - [[Reading Paths]] - [[Step 01 Discovery Call]] - [[The Agent Contract]] - [[Protocol at a Glance]] - [[The Brainstem Kernel]] - [[Sources and Provenance]] ======================================================================== FILE: Production Guide/Step 01 Discovery Call.md ======================================================================== --- title: Step 01 Discovery Call section: Production Guide status: published hook: How to run the discovery call whose transcript becomes the foundation for every later step. source: "docs/rapp-guide.html#step1" --- # Step 01 Discovery Call The **discovery call** captures the customer's biggest problems in their own words. Its **transcript** is the input to everything that follows. Lead with business pain, not with AI. Guide section: [Step 1 in the production guide](../rapp-guide.html#step1) ## At a glance - **Type:** Manual - **Duration:** 30-60 minutes, one focused conversation with the decision makers - **Owner:** Field Team, anyone who works with customers - **Output:** recording, transcript, named stakeholders ## The three critical questions ### 1. What are your biggest problems? This keeps the focus on business value, not technology. A good answer is specific and measurable. Example: field sales reps ask every day where to go, in what order, and what to do on arrival. A bad answer is "we need AI". ### 2. What data sources do you have? AI without data is useless. State this caveat up front: without data access, the project is severely limited. Typical sources: - **CRM systems:** Dynamics 365, Salesforce, custom systems - **Document repositories:** SharePoint, OneDrive, file shares - **Operational systems:** inventory, scheduling, ticketing - **External APIs:** weather, traffic, market data ### 3. How do you solve this manually today? The **manual process is the blueprint** for automation. You scale what they already do. You do not invent a new workflow. Users recognize their familiar process, just faster. ## How to run the call **Before:** - Enable recording (Teams auto-transcribe, or another transcription tool). - Tell participants the call is recorded. - Invite 1-2 key decision makers, not ten people. **During:** - Let them talk. Extract knowledge; do not pitch. - Ask "walk me through exactly what the end user does". - Get specific numbers ("20 hours per week"), not "inefficiencies". - Note competing solutions they mention. - Confirm data access. ## Red flags - "We just want to try AI" — no specific problem, so no MVP. - "We can't share any data" — AI needs data. - "We have 50 different problems" — you need **one** focused MVP. - "We're not sure who the decision maker is" — get the right person. ## Output and exit criteria - **Recording file:** MP4 or audio - **Transcript file:** plain text is ideal; a Teams `.vtt` works - **Key stakeholders:** names and roles mentioned on the call **Litmus test:** "If I had 6 Python agents and access to their data, could I build a prototype that solves this?" - Yes → go to [[Step 02 Transcript Analysis]]. - No → schedule a follow-up call. ## How rapp/1 underpins this step It does not, directly. The discovery call is a human conversation. The upstream RAPP/1 specification governs bytes, identity and the wire, not meetings. The link comes later. The "6 Python agents" in the litmus test become files that follow [[The Agent Contract]] in [[Step 05 Generate Agent Code]]. ## Related - [[Production Guide Overview]] - [[Step 02 Transcript Analysis]] - [[Step 03 Generate MVP Poke]] - [[The Agent Contract]] - [[Glossary]] ======================================================================== FILE: Production Guide/Step 02 Transcript Analysis.md ======================================================================== --- title: Step 02 Transcript Analysis section: Production Guide status: published hook: How the transcript is turned into structured project JSON and audited at Quality Gate 1. source: "docs/rapp-guide.html#step2" --- # Step 02 Transcript Analysis **Transcript analysis** turns the raw discovery transcript into structured **project JSON**. An AI agent does the extraction. A person audits the result. This is **Quality Gate 1**: did we extract the right problem? Guide section: [Step 2 in the production guide](../rapp-guide.html#step2) ## At a glance - **Type:** Audit (Quality Gate 1) - **Duration:** about 15 minutes; the AI is instant, the human review takes the time - **Owner:** Delivery Team, the people who will build the solution - **Input:** the transcript from [[Step 01 Discovery Call]] - **Output:** validated `[customer]-project.json`, audit sign-off, go/no-go decision ## The tool The **Transcript-to-Project Agent** is a Copilot Studio declarative agent. If its link is down, the guide includes a manual fallback prompt to paste into Copilot. How to use it: 1. Open the agent in Copilot Studio. 2. Paste the whole transcript. 3. The agent returns JSON with the extracted fields. 4. Save it as `[customer]-project.json` or import it into the project tracker. ## Example output From the guide (a fictional company): ```json { "id": "1735840999", "customerName": "Acme Insurance", "status": "planning", "type": "legal", "description": "Legal operations AI bot for contract automation", "stakeholders": "VP Legal, Legal Operations Manager", "competingSolution": "Salesforce", "agents": ["ContractTemplate", "ContractAnalysis", "ContractRouting"], "mvpUseCase": "NDA Automation Bot", "mvpDescription": "Automated NDA generation, analysis, and routing with approval workflows", "mvpTimeline": "6 weeks POC", "notes": "Competing with Salesforce, focus on contract automation. Latency requirement under 2 seconds.", "createdDate": "2025-10-15", "updatedDate": "2025-10-15" } ``` The prompt constrains some fields: - `status` is one of `planning`, `poc`, `active`, `production`, `completed`. Use `planning` unless a POC has started. - `type` is one of `legal`, `hr`, `it`, `compliance`, `customer-service`, `sales`, `finance`, `other`. - `agents` names are PascalCase, no spaces. ## The human audit checklist - **Customer name:** correct legal entity? - **Stakeholders:** all decision makers, correct titles? - **MVP use case:** matches what the customer said? - **Competing solutions:** noted? - **Timeline:** realistic and confirmed? - **Data sources:** captured? Common corrections: - One broad `ContractManagement` agent → three focused agents. - `status` "active" → "planning" (nothing is built yet). - Timeline "ASAP" → a concrete timeframe. ## Gate decision - **Pass:** the JSON accurately represents the problem → [[Step 03 Generate MVP Poke]]. - **Fail:** key information missing or wrong → follow-up call. **Do not proceed if:** - The MVP use case is vague ("improve efficiency"). - No data sources were identified. - The decision maker was not on the call. - The problem is "nice to have", not "must solve". Fifteen minutes here prevents weeks of building the wrong thing. ## How rapp/1 underpins this step Only lightly. The project JSON is a delivery-tracking record. The upstream RAPP/1 specification does not define its schema. One forward link is real. The `agents` array names the capabilities that become agent files in [[Step 05 Generate Agent Code]], each following [[The Agent Contract]]. ## Related - [[Step 01 Discovery Call]] - [[Step 03 Generate MVP Poke]] - [[Step 04 Customer Validation]] - [[Production Guide Overview]] - [[The Agent Contract]] ======================================================================== FILE: Production Guide/Step 03 Generate MVP Poke.md ======================================================================== --- title: Step 03 Generate MVP Poke section: Production Guide status: published hook: What an MVP poke is, what goes in it, and how it is sent to the customer before any code is written. source: "docs/rapp-guide.html#step3" --- # Step 03 Generate MVP Poke The **MVP poke** is a short, plain-language summary of what we think the customer needs. It asks one question: "This is what I heard — is it correct?" It is sent **before any code is written**. Guide section: [Step 3 in the production guide](../rapp-guide.html#step3) ## At a glance - **Type:** Manual (automation planned) - **Duration:** 1-2 hours - **Owner:** Delivery Team drafts; the Field Team sends it - **Input:** the validated project JSON from [[Step 02 Transcript Analysis]] - **Output:** a 1-2 page poke document and the email that carries it ## Why a poke, not a requirements document - **Lightweight:** 1-2 pages, not 20. - **Plain language:** written for business stakeholders. - **Invites feedback:** "Did we hear you right?", not "Sign off on these requirements". - **Fast:** sent within 24 hours of the discovery call. The poke is both a validation checkpoint and the **specification** that guides prototype generation. ## The five sections 1. **Problem statement** — 2-3 sentences in the customer's terms, with numbers. 2. **Proposed MVP solution** — what it does, 3-4 key capabilities, and **scope boundaries** (what it does not do). 3. **Data requirements** — a simple list of the data access needed. 4. **Success metrics** — measurable targets, such as planning time from 2-3 hours a day to 5 minutes. 5. **Timeline and next steps** — a simple week-by-week roadmap. ## The generation prompt The guide drafts the poke from the project JSON with this prompt: ``` Generate an MVP "poke" document based on this customer project JSON: [Insert validated project JSON from Step 2] The document should be: - 1-2 pages maximum - Written in plain business language (not technical jargon) - Structured as: Problem Statement, Proposed Solution, Data Requirements, Success Metrics, Timeline - Specific and measurable (not vague "improve efficiency") - Include scope boundaries (what we're NOT building) - End with clear next steps for customer to respond Tone: Professional but approachable. We're confirming we heard them correctly, not pitching a solution. ``` ## Sending it Whoever ran the discovery call emails the poke. The email asks: - Did we capture the problem correctly? - Is this MVP scope right, or should we adjust? - Are the data sources accessible? - Any concerns before we proceed? ## Output and exit criteria - **MVP poke document:** 1-2 pages, Word or PDF - **Email to customer:** sent with the document attached - **Timeline started:** the customer response window, usually 2-3 days Total human time so far is about 1.25 hours. If the customer says "that's not what we meant", you have saved 3-6 weeks. Any detail the customer adds is the **first feedback cycle**, before a line of code exists. Next: [[Step 04 Customer Validation]]. ## How rapp/1 underpins this step Not directly. The poke is a business document, and the upstream RAPP/1 specification does not govern it. Its scope boundaries do shape the build later. Each capability listed becomes an agent behind the single `/chat` endpoint, not a new API route. See [[The Wire]] and [[The Agent Contract]]. ## Related - [[Step 02 Transcript Analysis]] - [[Step 04 Customer Validation]] - [[Step 05 Generate Agent Code]] - [[Production Guide Overview]] - [[The Wire]] ======================================================================== FILE: Production Guide/Step 04 Customer Validation.md ======================================================================== --- title: Step 04 Customer Validation section: Production Guide status: published hook: How the customer signs off on the MVP scope at Quality Gate 2, and what to do for each possible answer. source: "docs/rapp-guide.html#step4" --- # Step 04 Customer Validation **Customer validation** is **Quality Gate 2**. The customer confirms in writing that the MVP poke describes what they need. This **locks scope** before any code is written. The guide calls it the most important gate. Guide section: [Step 4 in the production guide](../rapp-guide.html#step4) ## At a glance - **Type:** Audit (Quality Gate 2) - **Duration:** 1-2 days, mostly waiting for the customer - **Owner:** Field Team, who manages the customer conversation - **Input:** the poke from [[Step 03 Generate MVP Poke]] - **Output:** written approval, final poke, updated project JSON, green light to build ## Three possible outcomes ### 1. "Yes, that's exactly right" - Save the sign-off email and stakeholder names. - Mark the MVP "Approved - Ready for Development" in the tracker. - Go straight to [[Step 05 Generate Agent Code]]. ### 2. "Close, but here's what needs to change" - Capture **all** feedback in writing, never only by phone. - Ask the LLM to update the poke with the corrections. - Send poke v2. Repeat until you reach outcome 1. When the customer adds a requirement, choose: - **Add it to the MVP** and re-send the poke, or - **Move it to Phase 2** to deliver value faster. New requirements often change the design. Five agents may become six, with a new focused agent for the new need. The modular shape absorbs this without a rebuild. ### 3. "This isn't what we need" - Schedule a follow-up discovery call. - Go back to [[Step 01 Discovery Call]]. - **Do not** start development. ## Watch for scope creep Warning signs: - "Can we also add ten more features?" - "Actually, we need something completely different." - "My boss says we also need..." Use the poke as a **scope boundary**: lock this MVP first, then expand. ## Exit checklist Before moving on, confirm: - **Written confirmation** of the MVP scope. - **Stakeholder sign-off** from the budget holder, not only end users. - **Data access confirmed.** - **Timeline agreed.** - **Scope locked** — no "we'll figure it out later" items. ## Output - **Customer approval email**, saved as proof of scope. - **Final MVP poke** (v2 or v3) with all feedback included. - **Updated project JSON** with status `mvp-locked` and the approval date. - **Green light** to generate agent code. Time invested so far: about 2 hours of human time plus 1-2 days of waiting. The risk removed: weeks of building the wrong thing. ## How rapp/1 underpins this step Not directly. Sign-off is a business agreement, outside the upstream RAPP/1 specification. The modular point in outcome 2 does match the protocol's design. New capability is added as a new agent behind `/chat`, never as a new endpoint. See [[The Wire]] and [[The Agent Contract]]. ## Related - [[Step 03 Generate MVP Poke]] - [[Step 05 Generate Agent Code]] - [[Step 01 Discovery Call]] - [[Production Guide Overview]] - [[The Wire]] ======================================================================== FILE: Production Guide/Step 05 Generate Agent Code.md ======================================================================== --- title: Step 05 Generate Agent Code section: Production Guide status: published hook: How the locked MVP becomes Python agent files that follow the BasicAgent pattern. source: "docs/rapp-guide.html#step5; SPEC.md §8, §9.2, §11.1" upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Step 05 Generate Agent Code This step turns the locked MVP into **agent code**: single Python files the Brainstem or Azure Function can load. Usually one well-scoped agent is enough. Split into several agents only when the use case truly spans separate roles. Guide section: [Step 5 in the production guide](../rapp-guide.html#step5) ## At a glance - **Type:** Manual, with AI-assisted generation - **Duration:** minutes to scaffold; writing the business logic is still the real work - **Owner:** Technical Team - **Input:** the approved poke and project JSON from [[Step 04 Customer Validation]] - **Output:** `[agent_name]_agent.py` files, tested locally ## Then and now When the guide was first written, each agent took 2-3 weeks by hand. Today a scaffolded agent is generated, smoke-tested and hot-loaded in about fifteen seconds. A hand-written one is live the moment the file is saved. The library has 72 published patterns. 70 of them use one single-file agent with several deterministic operations. ## The process 1. Review the approved poke and project JSON. 2. Identify the capabilities the MVP needs. 3. Start from an existing agent template. 4. Write each agent in the **BasicAgent pattern**. 5. Save each as `[agent_name]_agent.py`. 6. Test locally before [[Step 06 Code Quality Review]]. The **RAPP Agent Generator** (with a manual fallback prompt in the guide) drafts the code from the MVP description. ## The rules every agent follows From the generator prompt: 1. Inherit from `BasicAgent`. 2. Class name in PascalCase, e.g. `ContractGenerationAgent`. 3. `self.name` in PascalCase with **no spaces**. 4. `perform()` **always returns a string** — never a dict or `None`. 5. Errors return descriptive strings; never raise. 6. Include complete JSON Schema `metadata` so the agent documents itself. 7. One capability per agent. Published agents run roughly 180-960 lines, median about 400. ## The template ```python from agents.basic_agent import BasicAgent import logging import json class YourAgentNameAgent(BasicAgent): def __init__(self): self.name = "YourAgentName" # NO SPACES! self.metadata = { "name": self.name, "description": "Clear description of when to call this agent and what it does", "parameters": { "type": "object", "properties": { "param1": { "type": "string|integer|array|etc", "description": "What this parameter is for" } }, "required": ["param1"] } } super().__init__(name=self.name, metadata=self.metadata) def perform(self, **kwargs): """ What this method does. Returns: String describing the result """ param1 = kwargs.get('param1') if not param1: return "Error: param1 is required" try: result = "Success: description of what happened" return result except Exception as e: return f"Error in {self.name}: {str(e)}" ``` The `metadata` is what the model reads to decide **when** to call the agent and with which parameters. ## How rapp/1 underpins this step This is where the protocol becomes concrete. - **New capability is a new agent, not a new endpoint.** The upstream RAPP/1 specification (§8) says new capability is "a new agent behind `/chat`, never a sibling REST route". Writing an agent file is exactly that. See [[The Wire]] and [[The Agent Contract]]. - **The kernel stays unchanged.** New implementation behavior must live outside the pinned Grail kernel (§11.1). Agents are dropped into the agents folder; the kernel file is not edited. See [[The Brainstem Kernel]]. - **One agent file can travel as a rapplication.** The `rapplication` egg variant (§9.2) is a ZIP that must include `rappid.json` and exactly one `agent.py` at the root. See [[The Egg]] and [[Identity and the Rappid]]. ## Related - [[The Agent Contract]] - [[Step 04 Customer Validation]] - [[Step 06 Code Quality Review]] - [[The Wire]] - [[The Egg]] - [[The Brainstem Kernel]] ======================================================================== FILE: Production Guide/Step 06 Code Quality Review.md ======================================================================== --- title: Step 06 Code Quality Review section: Production Guide status: published hook: What a reviewer checks in generated agent code at Quality Gate 3 before it is deployed. source: "docs/rapp-guide.html#step6; SPEC.md §8" upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Step 06 Code Quality Review The **code quality review** is **Quality Gate 3**. An experienced developer reads every generated agent for **security**, **error handling**, **integration** and **metadata quality**. Only approved code moves to deployment. Guide section: [Step 6 in the production guide](../rapp-guide.html#step6) ## At a glance - **Type:** Audit (Quality Gate 3) - **Duration:** 30-60 minutes for 6-10 agents - **Owner:** Technical Team Lead with Python and Azure experience - **Input:** agent files from [[Step 05 Generate Agent Code]] - **Output:** approved code, issue log, integration notes, green light to deploy ## The review checklist ### 1. Security - **No hardcoded credentials** — secrets come from environment variables. - **Input validation** — required parameters are checked before use. - **Parameterized queries** for any database access. - **File path sanitization** for any file reads. ### 2. Error handling - External calls wrapped in `try`/`except`. - Errors logged with context (agent name, parameters). - **Always return strings** — never `None`, a dict, or a raised exception. - One failing agent must not break the others. ### 3. Integration - Customer API endpoints are correct. - Field names match the customer's real system. - Auth method matches their setup (OAuth, API key, certificate). - Required packages are listed in `requirements.txt`. ### 4. Metadata - **Clear descriptions** so the model knows when to call the agent. - The `required` array is accurate. - Parameter descriptions include example values. - Fixed options use `enum`. ## Common fixes **Returns a dict instead of a string.** ```python # wrong return {"status": "success", "route": optimized_route} # fixed return f"Route generated successfully: {json.dumps(optimized_route)}" ``` The intelligence layer expects strings. **Missing error context.** Replace `return "Error occurred"` with a logged, specific message that names the inputs. **Vague description.** Replace `"Handles route planning"` with text that says what the agent does and which user requests should trigger it. ## Gate decision - **Pass:** all agents reviewed, minor fixes applied → [[Step 07 Deploy Prototype]]. - **Fail:** major logic errors or missing integrations → send feedback to the generator and regenerate. Review is a conversation with the AI: merge redundant agents, split overloaded ones, adjust details until the files meet the bar. The guide reports a 94% first-attempt pass rate and 231 executable demo cases. ## Why pass rates are high - The framework enforces one pattern: `BasicAgent`, JSON Schema metadata, string returns. - The generator learns from working agents. - Each agent does one thing, so it is easy to review. ## How rapp/1 underpins this step The string-return rule matches the wire. On success, `POST /chat` returns a JSON object whose `response` member is a string, with `agent_logs` as a string of one line per agent call (§8). Agents that return strings keep that contract intact. See [[The Wire]] and [[The Agent Contract]]. For the security side of the protocol itself, see [[Security Considerations]]. ## Related - [[Step 05 Generate Agent Code]] - [[Step 07 Deploy Prototype]] - [[The Agent Contract]] - [[The Wire]] - [[Security Considerations]] ======================================================================== FILE: Production Guide/Step 07 Deploy Prototype.md ======================================================================== --- title: Step 07 Deploy Prototype section: Production Guide status: published hook: How reviewed agents get running locally, in Azure, and in Copilot Studio, and how to verify the deployment. source: "docs/rapp-guide.html#step7; docs/rapp-guide.html#architecture; SPEC.md §8, §11.1" upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Step 07 Deploy Prototype **Deploying the prototype** means getting the reviewed agents to answer real questions. Locally there is nothing to deploy: install the Brainstem, drop the files in its agents folder, and ask. Move to **Azure Functions** and **Copilot Studio** when the customer needs access without your laptop. Guide section: [Step 7 in the production guide](../rapp-guide.html#step7) ## At a glance - **Type:** Manual - **Duration:** minutes locally; 1-2 hours for the cloud tiers, with scripts - **Owner:** Technical Team - **Input:** approved agents from [[Step 06 Code Quality Review]], project JSON, integration notes, the `microsoft/aibast-agents-library` repository - **Output:** a working prototype reachable from Teams or web chat, verified before the demo ## The cloud path ### 7.1 Deploy Azure infrastructure Use the **Deploy to Azure** button in the repository README. It provisions from `azuredeploy.json`: - Azure Function App (stateless intelligence layer) - Azure File Storage (agent code and user memory) - Application Insights - Networking and security configuration It completes in 5-10 minutes. ### 7.2 Run the setup script ``` git clone https://github.com/microsoft/aibast-agents-library.git cd aibast-agents-library ./deploy.sh # or deploy.ps1 on Windows ``` ### 7.3 Deploy your agents Copy the approved `.py` files into the agents location: deploy from VS Code, or drag them into the File Storage `agents` folder. Agents **hot-load** with no restart. In Azure they refresh within five minutes. ### 7.4 Connect to Copilot Studio 1. Download `solutions//exports/-copilot-studio-solution.zip` and its deployment settings JSON. 2. Import the solution in Copilot Studio. 3. Set environment variables (Function URL, API key). 4. Enable channels: Teams, Web, Outlook. 5. Publish. ## Verification checklist | Check | How | Expected | |---|---|---| | Function App running | Portal → Overview | Status "Running" | | Agents loaded | File Storage → agents folder | Your `.py` files | | Function responds | POST to Function URL | Lists available agents | | Copilot Studio connected | Test chat | Replies to "Hello" | | Agent calls work | Ask for one agent | Agent runs, returns result | | Memory persists | Tell it something, ask later | It remembers | ## Common issues - **Timeouts:** raise `functionTimeout` in `rapp_ai/host.json` and republish. A portal edit is overwritten by the next deployment. - **Copilot Studio can't reach the Function:** rarely CORS. Check the Function is running and the key is right. Narrow `allowedOrigins` before production. - **Agents not loading:** the Function App managed identity is missing a storage role. The storage account disallows shared keys, so no connection string will work. ## Rehearse before the demo Role-play every MVP scenario. Check that: - The model picks the **right agent** for each request. - **Parameters** arrive correctly. - Responses are useful and well formatted. - **Invalid inputs fail gracefully.** - Memory works across messages. Then move to [[Step 08 Demo Review]]. ## How rapp/1 underpins this step - **One endpoint to test.** Every channel reaches the agents through the same wire: `POST /chat` with `user_input`, answering with `response`, `agent_logs` and `session_id`. `GET /health` is the liveness probe (§8). See [[The Wire]]. - **Deploying agents does not change the kernel.** New behavior lives outside the pinned Grail kernel (§11.1). Hot-loading agent files is that rule in practice. See [[The Brainstem Kernel]] and [[Distros and Pinning]]. - **Later stages.** Qualified releases and progressive rollout to production are covered by [[RAPP CICD]] and [[RAPP Deploy]], used from [[Step 13 Production Deployment]]. ## Related - [[Step 06 Code Quality Review]] - [[Step 08 Demo Review]] - [[The Wire]] - [[The Brainstem Kernel]] - [[RAPP Deploy]] - [[Failure Atlas]] ======================================================================== FILE: Production Guide/Step 08 Demo Review.md ======================================================================== --- title: Step 08 Demo Review section: Production Guide status: published hook: How the customer first sees the working prototype, and how Quality Gate 4 decides what happens next. source: docs/rapp-guide.html#step8 --- # Step 08 Demo Review **Demo Review** is the first time the customer sees their agents actually working. You record the live prototype solving the agreed MVP scenarios and send it for feedback. This step is **Quality Gate #4**: approve, iterate, or stop scope creep. Guide section: [Step 8 in the production guide](../rapp-guide.html#step8) ## What this step is - **Goal:** film the working prototype solving the MVP scenarios, then collect the customer's verdict. - **Rule:** no slides, no mockups. Real execution only. - **Time:** 2-4 hours in total. - Record demo: 30-60 minutes. - Optional edit: 30 minutes. - Customer review: 1-2 days. - Feedback session: 30-60 minutes. ## Who does it - **Human:** records the screen, narrates, and collects customer feedback. - **Automation:** the agents run the MVP scenarios in real time. ## Inputs (from Step 07) - **Live prototype**, deployed and tested ([[Step 07 Deploy Prototype]]). - **M365 Copilot access** through Teams, Outlook, or web. - **Rehearsal notes** on which scenarios work. - **Approved MVP doc**, signed by the customer in [[Step 04 Customer Validation]]. ## How to record 1. **Prepare.** Open M365 Copilot (Teams or web, whichever is cleaner). Load the approved scenarios. Start a screen recorder. 2. **Record each MVP scenario.** Show the agent being called and the real answer. 3. **Show behind the scenes (optional).** Briefly show agent calls in Application Insights. This proves it is not a mockup. 4. **Narrate the value.** Before: name the business problem. During: say what the agent is doing. After: state the result. ### The "waiter" pattern The customer sees a simple conversation. Behind it, the LLM takes the request, calls the right agent with parameters, and returns a clean answer. The user never needs to see the orchestration. ## Sending the demo The guide gives an email template. It lists each scenario with timestamps and asks **two questions**: 1. Do these agents solve the business problem as you described it? 2. Is there anything you'd like adjusted before we move to production? Then hold a 30-60 minute feedback call. Useful questions: - "Did the agents solve the problem as you described it?" (scope alignment) - "Were the results accurate and useful?" (data integration quality) - "Is there anything you'd change or add?" (scope creep detector) - "Can you see this being used by your team?" (adoption readiness) - "What would production deployment look like?" (sets up Steps 11-14) ## Outputs - **Demo video:** a 10-15 minute recording showing all MVP scenarios. - **Customer feedback notes.** - **Approval email:** written confirmation to proceed. - **Iteration log** (if needed). - **Green light for production:** a customer-approved prototype ready for final polish. Checklist before [[Step 09 Generate Video Demo]]: - The customer watched the full demo. - All MVP scenarios were demonstrated. - Written approval was received. - No major scope changes. - The production timeline was discussed. ## The gate: three outcomes - **APPROVED.** Proceed to [[Step 09 Generate Video Demo]]. - **ITERATE.** Loop back to [[Step 05 Generate Agent Code]], regenerate the affected agents, redeploy, re-record. - **SCOPE CREEP.** Stop. Explain it is outside MVP scope. Keep the original scope or restart at [[Step 01 Discovery Call]]. **The "while we're at it" trap:** new capabilities mean new discovery, new MVP, and new testing. Log them for the next phase and finish this MVP first. ## How rapp/1 underpins this step - The "waiter" pattern is the **agent contract** at work: the model chooses an agent and calls it through one chat surface. See [[The Agent Contract]] and [[The Brainstem Kernel]]. - An ITERATE loop goes back to [[Step 05 Generate Agent Code]] to regenerate the affected agents, then redeploys and re-records. ## Related - [[Step 07 Deploy Prototype]] - [[Step 09 Generate Video Demo]] - [[Step 04 Customer Validation]] - [[The Agent Contract]] - [[Production Guide Overview]] ======================================================================== FILE: Production Guide/Step 09 Generate Video Demo.md ======================================================================== --- title: Step 09 Generate Video Demo section: Production Guide status: published hook: How to turn the approved prototype into a produced, narrated demo for executives. source: docs/rapp-guide.html#step9 --- # Step 09 Generate Video Demo **Generate Video Demo** produces a polished, shareable video of the solution. It is for executives, sales decks, and internal evangelism. Unlike the raw screen recording in Step 08, this is a **produced demo** with scripted narration and polished visuals. Guide section: [Step 9 in the production guide](../rapp-guide.html#step9) ## What this step is - **Goal:** a self-contained demo video with Azure TTS narration. - **Time (manual):** 3-4 hours. - Build the demo JSON in the Local-First Chat Animation Studio: 1-2 hours. - Script narration and timing: 1 hour. - Test and refine: 1 hour. - **Automation vision:** a Video Demo Generator creates the demo JSON from a prototype walkthrough, cutting the time to about 30 minutes. ## Who does it - **Human:** builds the demo structure, writes the script and narration, and adjusts timing. - **Tool:** the **Video Demo Generator**, a Copilot Studio declarative agent. The guide also includes a copy-paste fallback prompt if the agent link is not working. ## Inputs (from Step 08) - **Customer-approved prototype** from [[Step 08 Demo Review]]. - **Screen recording** of real agent execution. - **MVP documentation:** business value, metrics, use cases. - **Project JSON:** customer, stakeholders, timeline (from [[Step 02 Transcript Analysis]]). ## The demo JSON The generator returns one JSON document with four parts: - `demoMetadata` - title, customer, industry, `totalDuration`, `voiceName`, `createdDate`. - `demoSteps` - 7-10 steps, each with `id`, `name`, `duration`, `voiceText`, and a `narrator` overlay. - `chatInteractions` - the user, system, and agent messages shown per step. - `agentCards` - an agent `title`, `status`, and `details` per step. A fragment of the required structure, as given in the guide: ```json { "demoMetadata": { "title": "[Customer Name] AI Agent Demo", "customer": "[Customer Name]", "industry": "[Industry: legal, sales, hr, it, etc.]", "totalDuration": "[Total seconds, e.g., 75]", "voiceName": "en-US-GuyNeural", "createdDate": "[YYYY-MM-DD]" } } ``` ## The narrative arc Every demo follows the same three-part story: 1. **Problem hook (8-10 s):** the painful manual process. 2. **Solution demo (40-50 s):** 3-4 agent capabilities with specific examples. 3. **Business impact (10-15 s):** ROI, metrics, scale. Writing rules from the prompt: - `voiceText` is written for speech, about 150 words per minute. - `duration` matches the narration (20 words is about 8000 ms). - Overlays carry specific metrics: time saved, accuracy, cost reduction. - Use the real agent names from the implementation. ## Output and exit - **Demo JSON file:** `demos/[customer-name]-demo.json` - **Standalone HTML demo:** a self-contained file with narration. - **Hosted URL** (optional): GitHub Pages or an internal server link. - **MP4 video** (optional): a recorded playthrough for PowerPoint. - **Usage instructions:** how to view, navigate, and share. Quality check before sharing: - Metrics match the project JSON. - Narration timing is natural. - Agent cards appear at the right steps. - The customer name is spelled correctly. - The demo works on mobile. These go to the customer for sign-off in [[Step 10 Final Demo Review]]. ## How rapp/1 underpins this step This step is presentation work. The upstream RAPP/1 specification does not define the demo JSON format. The link to the protocol is indirect: the agent names and behavior shown must match the real agents that passed [[Step 06 Code Quality Review]] and run under [[The Agent Contract]]. ## Related - [[Step 08 Demo Review]] - [[Step 10 Final Demo Review]] - [[Step 07 Deploy Prototype]] - [[The Agent Contract]] - [[Production Guide Overview]] ======================================================================== FILE: Production Guide/Step 10 Final Demo Review.md ======================================================================== --- title: Step 10 Final Demo Review section: Production Guide status: published hook: How the customer approves the produced video demo for executive sharing at Quality Gate 5. source: docs/rapp-guide.html#step10 --- # Step 10 Final Demo Review **Final Demo Review** is **Quality Gate #5**. The customer confirms the polished video accurately represents their solution. Once approved, the demo is locked and can be shared with executives, board members, or field teams. Guide section: [Step 10 in the production guide](../rapp-guide.html#step10) ## What this step is - **Goal:** final customer approval of the video demo. - **Time:** 30-60 minutes (one review call). - **Decision:** approve for production use, or request adjustments. ## Who does it - **Delivery team:** walks the customer through the demo and the checklist. - **Customer:** checks facts, tone, and branding, and grants distribution permission. ## Inputs (from Step 09) - **Video demo** (HTML or MP4) with Azure TTS narration, from [[Step 09 Generate Video Demo]]. - **Demo JSON:** the full script with steps, metrics, and narration. - **Distribution plan:** email, hosted URL, or embedded in a deck. ## Review checklist | Review item | What to check | |---|---| | **Metrics accuracy** | All numbers match reality: time saved, ROI, accuracy gains. | | **Messaging tone** | Narration fits the audience (executives vs. field users). | | **Company branding** | Customer name spelled correctly; no competitor references. | | **Technical accuracy** | Integration points and systems mentioned are correct. | | **Shareability** | Customer is comfortable with internal distribution. | ## The gate: two outcomes - **APPROVED.** The demo is locked. Proceed to [[Step 11 Production Planning]]. - **ITERATE.** Minor fixes to narration, metrics, or branding. Fix and re-review. ## Outputs - **Approved demo files:** final HTML or MP4, locked for distribution. - **Distribution permission:** customer sign-off for executive sharing. - **Usage guidelines:** who can see it and how to present it. ## Where this sits in the timeline The guide groups Steps 9-10 as about **one day** of work. After this gate, the project leaves the prototype phase. Steps 11-14 are the production phase, mostly owned by the customer's IT team. ## How rapp/1 underpins this step This is a human review gate. The upstream RAPP/1 specification does not define it. The practical tie-in: "metrics accuracy" and "technical accuracy" are only checkable because the demo shows the real deployed agents, not a mockup. Those agents follow [[The Agent Contract]]. ## Related - [[Step 09 Generate Video Demo]] - [[Step 11 Production Planning]] - [[Step 08 Demo Review]] - [[Production Guide Overview]] - [[Reading Paths]] ======================================================================== FILE: Production Guide/Step 11 Production Planning.md ======================================================================== --- title: Step 11 Production Planning section: Production Guide status: published hook: How the prototype's requirements for security, compliance, and rollout are defined before production. source: docs/rapp-guide.html#step11; protocols/rapp-cicd/1/SPEC.md §1-3; protocols/rapp-deploy/1/SPEC.md §1-4 upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Step 11 Production Planning **Production Planning** turns a working prototype into a plan for a production system. You work with the customer's IT, Security, and Compliance teams. The result is a **requirements document** and a **phased rollout plan**. Guide section: [Step 11 in the production guide](../rapp-guide.html#step11) ## What this step is - **Goal:** define production deployment requirements with the customer. - **Time:** 3-7 days of meetings and documentation. - **Owner:** Technical Team. In the guide's team setup (Station 4, Steps 11-14) the owner is the customer IT team, with Team Member C for support escalation. ## Inputs - The locked, approved demo from [[Step 10 Final Demo Review]]. - The prototype and its reviewed agents from [[Step 07 Deploy Prototype]]. ## Questions for IT and Security - **Data residency:** where may data be stored (US, EU, on-prem)? - **Authentication:** SSO required? Azure AD integration? - **Network access:** public internet, or private endpoints? - **Audit logging:** which events must be logged? - **Encryption:** at rest and in transit. - **Compliance frameworks:** HIPAA, SOC 2, GDPR, FedRAMP? ## Prototype vs. production - **Prototype:** one Azure Function App, public endpoints, dev subscription. - **Production:** redundant deployments, private endpoints, the customer's subscription. Common security additions: - Azure AD authentication (no anonymous access) - Private Link for the Function App - Azure Key Vault for secrets, not environment variables - Application Gateway with WAF - DDoS protection - Managed Identity for service-to-service auth - Azure Monitor alerts for security events ## Rollout strategy | Phase | Users | Duration | Success criteria | |---|---|---|---| | 1: Pilot | 5-10 power users | 2 weeks | 80% adoption, no critical bugs | | 2: Early Adopters | 25-50 users | 4 weeks | Positive NPS, feature requests captured | | 3: General Availability | All users | 8 weeks | ROI metrics achieved, support tickets low | ## Outputs - **Production requirements doc:** security, compliance, infrastructure. - **Rollout plan:** phased schedule with success metrics. - **Support plan:** who handles questions and bugs. - **Training materials:** guides, video tutorials, FAQ. These go to [[Step 12 Security Sign-off]]. ## How rapp/1 underpins this step The upstream RAPP/1 specification has two operational profiles that match this planning work. See [[RAPP CICD]] and [[RAPP Deploy]]. - **Release identity.** In `rapp-cicd/1`, a `rapp-cicd/1-release` payload names the complete candidate before qualification: source commit and tree, the exact artifact, and the pinned Grail kernel. Its identity is its particle hash ([[Content Addressing]]). - **Promotion policy.** A `rapp-cicd/1-policy` payload declares the ordered promotion path and required evidence. Planning which reviews must pass maps onto this. - **Rollout plan.** In `rapp-deploy/1`, a `rapp-deploy/1-plan` covers topology, waves, health budgets, state, data, and recovery. - **Phased waves.** Waves begin with `shadow` at zero traffic, only increase, and end with `global` at 10,000 basis points. The guide's Pilot, Early Adopters, and GA phases are the business view of the same idea. - **Rollback target.** An authorized plan binds a resolvable, previously authorized rollback release. Neither profile prescribes a cloud provider, so the Azure controls above are the customer's choice, not protocol requirements. ## Related - [[Step 10 Final Demo Review]] - [[Step 12 Security Sign-off]] - [[RAPP CICD]] - [[RAPP Deploy]] - [[Distros and Pinning]] - [[Security Considerations]] ======================================================================== FILE: Production Guide/Step 12 Security Sign-off.md ======================================================================== --- title: Step 12 Security Sign-off section: Production Guide status: published hook: How IT, Security, and Compliance formally approve production deployment at Quality Gate 6. source: docs/rapp-guide.html#step12; protocols/rapp-cicd/1/SPEC.md §1-5; SPEC.md §14 upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Step 12 Security Sign-off **Security Sign-off** is **Quality Gate #6**, the last human gate before production. The customer's IT, Security, and Compliance teams formally approve that the system meets every production requirement. Nothing goes live without **written approval**. Guide section: [Step 12 in the production guide](../rapp-guide.html#step12) ## What this step is - **Goal:** formal production approval from the customer's IT, Security, and Compliance teams. - **Time:** 1-3 weeks (review process, pen testing, compliance audit). - **Note:** the guide says production is "mostly waiting for security and compliance approvals." It runs async and does not consume delivery team time. ## Inputs - The production requirements doc, rollout plan, and support plan from [[Step 11 Production Planning]]. - The reviewed agent code from [[Step 06 Code Quality Review]]. ## Security review checklist - **Penetration testing:** third-party audit completed. - **Vulnerability scan:** no critical or high-severity issues. - **Code review:** security team reviewed the agent code. - **Access controls:** RBAC configured, least privilege enforced. - **Secrets management:** all credentials in Azure Key Vault. - **Logging and monitoring:** security events captured and alerted. ## Compliance review checklist - **Data classification:** PII/PHI handling documented. - **Data retention:** policies set for user memory and logs. - **Audit trail:** every agent action logged with user context. - **Frameworks:** SOC 2, HIPAA, GDPR requirements met. - **Third parties:** vendor BAAs signed where needed. ## The gate: three outcomes - **APPROVED.** Proceed to [[Step 13 Production Deployment]]. - **CONDITIONAL APPROVAL.** Fix the minor issues and re-submit. - **BLOCKED.** Major issues. Back to [[Step 11 Production Planning]] for redesign. ## Outputs - **Security sign-off:** written approval from the CISO or Security team. - **Compliance sign-off:** approval from Compliance or Legal. - **Pen test report** from the third-party audit. - **Production deployment authorization:** go-live approval. ## How rapp/1 underpins this step - **Approval bound to exact bytes.** In [[RAPP CICD]], evidence records (`rapp-cicd/1-evidence`) and the decision (`rapp-cicd/1-promotion`) refer to one exact release candidate. A changed payload has a new particle hash, so it is a different release. An approval cannot silently carry over to changed code. - **Signed, not just recorded.** Authoritative payloads travel in signed RAPP/1 frames. A local unsigned file is a draft and cannot authorize promotion. See [[The Frame]] and [[Trust and Signatures]]. - **Kernel drift is a blocker.** The release-shaped artifact must contain the pinned Grail bytes before its tests and approval. A digest mismatch is a blocking `kernel-drift` finding. See [[Security Considerations]] and [[Distros and Pinning]]. The upstream specification does not replace pen tests or compliance audits. It makes the approved candidate unambiguous. ## Related - [[Step 11 Production Planning]] - [[Step 13 Production Deployment]] - [[Security Considerations]] - [[RAPP CICD]] - [[Trust and Signatures]] ======================================================================== FILE: Production Guide/Step 13 Production Deployment.md ======================================================================== --- title: Step 13 Production Deployment section: Production Guide status: published hook: How the approved system is deployed to the customer's environment and rolled out to pilot users. source: docs/rapp-guide.html#step13; protocols/rapp-deploy/1/SPEC.md §1-5 upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Step 13 Production Deployment **Production Deployment** moves the system from prototype to production. It runs in the customer's Azure subscription with every security and compliance control. Then a **phased rollout** begins with pilot users. Guide section: [Step 13 in the production guide](../rapp-guide.html#step13) ## What this step is - **Goal:** deploy the approved system and start the pilot. - **Time:** 2-3 days of deployment, then a 2-4 week pilot. - **Owner:** Technical Team. ## Inputs - **Production deployment authorization** from [[Step 12 Security Sign-off]]. - The rollout and support plans from [[Step 11 Production Planning]]. - The reviewed agents from [[Step 06 Code Quality Review]]. ## Deployment steps **1. Infrastructure** 1. Run the production ARM template (with the Step 11 security additions). 2. Configure Azure AD authentication. 3. Set up Private Link endpoints. 4. Configure Application Gateway and WAF. 5. Enable Azure Monitor alerts. 6. Configure backup and disaster recovery. **2. Agents** 1. Copy reviewed agents from prototype to production File Storage. 2. Verify agents load in the production Function App. 3. Test one agent call with production data. 4. Configure production data source connections. 5. Validate memory persistence in production Azure Storage. **3. M365 integration** 1. Import the Copilot Studio solution to production. 2. Configure the production Azure Function URL. 3. Enable the Teams channel for the pilot group. 4. Test end to end: Teams → Copilot → Function → Agents → data sources. 5. Verify SSO works. **4. Pilot onboarding** - Send a welcome email with access instructions. - Run a 30-minute training session. - Provide a Teams support channel. - Set expectations: this is Phase 1, and feedback shapes improvements. ## Monitoring during the pilot (weeks 1-2) - **Daily check-ins** on Application Insights errors. - **Weekly survey** to pilot users (NPS, issues, feature requests). - **Performance metrics:** response time, success rate, usage frequency. - **Hot fixes:** critical bugs within 24 hours. ## Outputs - **Production system** with all security controls. - **Pilot users active:** 5-10 people using agents daily. - **Monitoring dashboard** for usage and performance. - **Support process** with a defined escalation path. ## How rapp/1 underpins this step [[RAPP Deploy]] (`rapp-deploy/1`) describes this step in protocol terms. - **No in-place changes.** `candidate_isolated` must be true and `in_place_mutation` must be false. Any behavior-affecting change creates a new release. A pilot hot fix is therefore a new release, not an edit to the running one. - **Serving and candidate lineages.** The release receiving traffic and the release under exposure are kept separate. - **Cells.** Every deployment uses `topology.mode: "cellular"`: independently observable, isolatable failure domains. - **Health is evidence.** A `rapp-deploy/1-health` record is one candidate-bound observation window in one cell. It cannot label itself healthy when a budget failed. - **Decisions.** A `rapp-deploy/1-decision` is advance, complete, hold, rollback, or quarantine. - **User work is kept.** Acknowledged user work must not be discarded by rollback. The kernel under the agents stays pinned. See [[The Brainstem Kernel]] and [[Distros and Pinning]]. ## Related - [[Step 12 Security Sign-off]] - [[Step 14 Post-Deployment Review]] - [[RAPP Deploy]] - [[RAPP CICD]] - [[The Brainstem Kernel]] - [[Failure Atlas]] ======================================================================== FILE: Production Guide/Step 14 Post-Deployment Review.md ======================================================================== --- title: Step 14 Post-Deployment Review section: Production Guide status: published hook: How the pilot is measured against the MVP targets and how Phase 2 is planned. source: docs/rapp-guide.html#step14; docs/rapp-guide.html#scaling; protocols/rapp-deploy/1/SPEC.md §4-5 upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Step 14 Post-Deployment Review **Post-Deployment Review** closes the loop. After 2-4 weeks of pilot use, you compare real results against the MVP targets. You validate **ROI** and plan **Phase 2**. Guide section: [Step 14 in the production guide](../rapp-guide.html#step14) ## What this step is - **Goal:** measure success, gather lessons, plan the next phase. - **Time:** 1-2 hours (a review meeting with the customer). - **When:** 2-4 weeks after pilot launch in [[Step 13 Production Deployment]]. ## Inputs - Pilot monitoring data and weekly survey results from Step 13. - The target metrics agreed in the MVP ([[Step 04 Customer Validation]]). - The projected savings shown in the demo ([[Step 09 Generate Video Demo]]). ## Quantitative review | Metric | Target (from MVP) | |---|---| | Time saved per user per day | 45 minutes | | Agent accuracy | 95% | | User adoption rate | 80% | | Agent calls per day | 20+ per user | Each row is filled with the measured value and marked met, partial, or missed. ## Qualitative review - **User satisfaction (NPS)** from pilot surveys. - **Top feature requests** for Phase 2. - **Pain points:** what is not working. - **Unexpected use cases.** ## Lessons learned - **What worked:** most-used agents, training that landed, smooth integrations. - **What needs work:** accuracy issues, where users got stuck, unreliable data connections. ## Phase 2 options - **Wider rollout,** for example from 10 pilot users to 50+. - **New agents** from user requests. - **More integrations.** - **Advanced features:** multi-agent workflows, proactive alerts, scheduled tasks. ## Worked example from the guide A field sales pilot after 4 weeks: - 10 pilot users × 42 min saved per day (target was 45). - 4 weeks × 5 days = 20 days. - Total: 140 hours saved across 10 users. - Extrapolated to 200 users: 35,000 hours per year (close to the 37,500 target). - **Decision:** proceed with Phase 2 to all 200 reps. ## Outputs - **Success metrics report.** - **User feedback summary:** NPS, quotes, requests. - **ROI validation:** actual vs. projected savings. - **Phase 2 proposal:** a 3-6 month roadmap. - **Case study** (optional) for similar projects. ## The whole framework The guide's summary: production deployment takes 3-5 weeks, mostly waiting for approvals. Steps 11-14 run async and do not block the delivery team, which is how a small team runs many projects at once. Phase 2 requests that need new capability start a new cycle at [[Step 01 Discovery Call]]. ## How rapp/1 underpins this step - **Expanding the rollout** maps onto later waves in [[RAPP Deploy]]. Traffic only increases, previously exposed cells are never removed, and the last wave is `global` at 10,000 basis points. - **Each advance needs fresh evidence.** A decision cannot advance until every selected cell meets its observation duration and healthy windows. - **New agents are new releases.** Any behavior-affecting change creates a new [[RAPP CICD]] release, so Phase 2 work goes back through qualification and promotion. ## Related - [[Step 13 Production Deployment]] - [[Step 01 Discovery Call]] - [[RAPP Deploy]] - [[RAPP CICD]] - [[Production Guide Overview]] ======================================================================== FILE: Protocol/Canonicalization.md ======================================================================== --- title: Canonicalization section: Protocol status: published hook: How does rapp/1 turn any JSON value into one exact byte string? source: "SPEC.md §4; book/02-canonicalization.md; book/A-reference-manual.md §A.1; conformance/vectors.json (4_canonical, 4_refuse)" upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Canonicalization **Canonicalization** turns a JSON value into **one exact byte string**. The same value always gives the same bytes, on every machine. Every hash in rapp/1 is computed over these bytes, so this is the foundation of the whole protocol. ## The rule in one line `canonical(v)` is the UTF-8 byte string produced by **RFC 8785 JCS** (JSON Canonicalization Scheme) for the value `v`. It is defined only over I-JSON (RFC 7493). JCS fixes: - **member-name order** (by UTF-16 code unit), - **string escaping**, - **number format** (ECMAScript `Number::toString`). There is **no insignificant whitespace** and **no byte-order mark** in the output. ## Example From the conformance vectors. The input value: ```json { "a": [3, 2], "b": 1, "c": { "x": 2, "y": 1 } } ``` has the canonical form: ``` {"a":[3,2],"b":1,"c":{"x":2,"y":1}} ``` Whitespace is gone. Array order is kept. Object keys are always emitted in sorted order. ## What gets refused An implementation **MUST refuse, never repair**, a value that contains, at any depth: - **duplicate member names** in one object; - an **unpaired UTF-16 surrogate**, or a **Unicode noncharacter** (U+FDD0–U+FDEF, or any code point whose low 16 bits are FFFE or FFFF); - a **number that does not survive the binary64 round-trip**; - a canonical form **over 1 MiB**, or nesting **deeper than 64** (the root is depth 1). Refusal is whole, never partial. Input must also be well-formed UTF-8: - a leading **byte-order mark is refused** (not stripped); - UTF-16 and UTF-32 input is **never transcoded**. Refused inputs from the conformance vectors: | JSON text | Why | |---|---| | `{"a":1,"a":2}` | duplicate member name | | `{"n": 9007199254740993}` | integer does not survive binary64 round-trip | | `{"n": 1e999}` | non-finite after parse | | `"\ud800"` | unpaired UTF-16 surrogate | By contrast, `0.1` is accepted, because it round-trips. ## No normalization - RAPP applies **no Unicode normalization** when hashing, storing or re-emitting an existing value. - Strings are kept verbatim. Equality is **code-point equality**. - A producer creating a **new** human or identifier string (slug, kind, label, `payload` object key) **MUST** emit it in **NFC**. - A producer building a frame or packing an egg **MUST refuse** a `payload` member name that is not in NFC, or that contains an unassigned code point. - Consumers do not test frame contents for NFC (egg paths are the exception — see [[The Egg]]). ## Why "refuse, do not repair" If a reader silently fixes bad input, two readers can fix it differently. Then the same input produces two different hashes, and the protocol's core promise breaks. Refusal keeps every conformant implementation in agreement. See the [[Failure Atlas]] for related failures. ## Migration note The upstream specification records drift C4: an older `canonicalize()` (sorted-key `JSON.stringify`) matches JCS only for string-only payloads. It **MUST** be replaced by the JCS implementation of record, imported rather than re-typed. ## Related - [[Content Addressing]] - [[Protocol Layers]] - [[The Frame]] - [[Conformance and Drift]] - [[Implementing the Protocol]] ======================================================================== FILE: Protocol/Conformance Classes.md ======================================================================== --- title: Conformance Classes section: Protocol status: published hook: What does an implementation have to do to claim it conforms to rapp/1, and what extra rules apply to the Grail kernel and production operations? source: SPEC.md §11; book/10-conformance-and-drift.md; book/A-reference-manual.md §A.8 upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Conformance Classes A **conformance class** is a named role an implementation can claim: **Producer**, **Consumer**, or **Router/Mirror**. Each role has a fixed list of duties. Claiming a role means doing all of them, with no legacy forms and no silent repairs. Two extra rule sets cover the pinned Grail kernel and production operations. ## The three classes **Producer** emits only: - §4 canonical JSON bytes (see [[Canonicalization]]); - §5 domain-separated full SHA-256 addresses (see [[Content Addressing]]); - rappids minted per §6.2 (see [[Identity and the Rappid]]); - eleven-key frames (see [[The Frame]]); - `rapp/1-egg` variants (see [[The Egg]]); - and **no legacy form**. **Consumer**: - runs the full §7.5 frame checklist, including step 1a stream binding; - runs §9.3 egg verification; - runs §10 signature, key-discovery, and tombstone checks (see [[Trust and Signatures]]); - canonicalizes legacy ids on read; - refuses on any failure, and never repairs, reparents, or rolls back. **Router/Mirror**: - invents no endpoints beyond the [[The Wire|wire]]; - declares that the upstream RAPP/1 specification governs protocol semantics; - serves only provenance-stamped, hash-matching mirrors. ## The Grail kernel pin (§11.1) An estate declares its Grail kernel through one `grail-kernel` registry entry. See [[The Registry]] and [[The Brainstem Kernel]]. - The Grail is identified by `grail_id`, never by a branch, tag, repository name, or product label. - Every ring and stage — development, qualification, Preprod, installation, production — compares the candidate's Grail bytes to the pinned SHA-256 and length. - A missing, changed, substituted, or unmeasured Grail byte is `kernel-drift` and **must** fail closed. Approval or urgency cannot waive it. - A pipeline **must not** test a different file and then restore the pinned file. The release-shaped artifact itself must pass the gates. - New behavior **must** live outside the Grail kernel. If it cannot, the implementation reports an incompatibility. It never edits the Grail and keeps the same identity. - Different kernel bytes are a different Grail, with a new `grail_id`. A successor may name a `predecessor` but never overwrites the old one. - Once activated, the full canonical entry is persisted. Later removal or mutation is a permanent `kernel-drift` refusal. This is why downstream work pins the kernel and builds around it. See [[Distros and Pinning]]. ## Operational conformance profiles (§11.2) rapp/1 is the **substrate**. Two **operational profiles** sit on top of it. They say how a production AI changes without changing the substrate or the serving system under users. They are rapp/1 **applications**, not new wire versions. - **RAPP CI/CD** (`rapp-cicd/1`, `protocols/rapp-cicd/1/SPEC.md`) — immutable release capsules, ordered qualification evidence, exact-candidate promotion, Preprod, and rollback/restore proof. See [[RAPP CICD]]. - **RAPP Deploy** (`rapp-deploy/1`, `protocols/rapp-deploy/1/SPEC.md`) — isolated serving/candidate lineages, cellular rollout, progressive exposure, expiring AI-health evidence, quarantine, and exact rollback. See [[RAPP Deploy]]. §11.2 names only these two. [[RAPP Work]] (`rapp-work/1`) is a separate operations note that binds a work organization to its catalog, releases, and rollback targets. Rules that bind both profiles: 1. Payloads **MUST** be §4 canonical I-JSON, identified by `H("rapp/1:particle", payload)`. 2. Authoritative payloads **MUST** travel in signed rapp/1 frames using a registered compatible kind. Local unsigned files are drafts, fixtures, or caches and cannot authorize promotion or traffic. 3. They **MUST NOT** add a transport endpoint beside §8 `POST /chat`, redefine any rapp/1 primitive, or weaken §11.1. 4. An estate activates a profile through an authenticated §13.3 `protocol` registry entry pinning exact repository, path, and SHA-256. A moving branch is discovery, never authority. 5. A claim of **RAPP production conformance** requires both profiles. Core Producer, Consumer, and Router/Mirror implementations stay conformant without them. 6. Fixed envelope keys carry the safety invariants. Policy-defined check identifiers, component kinds, health objectives, and resilience controls are extension points; adding one changes neither the profile token nor the rapp/1 wire. 7. A consumer **MUST** refuse unknown **required** policy semantics. It may preserve and relay unknown optional evidence, but never count it as meeting a requirement it does not implement. The reference validators are `rapp_cicd.py` and `rapp_deploy.py`; controlled profile vectors are in `operations_conformance.py`. JSON Schemas define structure; the validators enforce ordering, identity, temporal, and cross-document rules a schema cannot express. ## Proving it: the controlled suite `conformance.py` is the executable form of the core rules: ```bash python3 conformance.py ``` It ends with a line like: ```text ── 23 controlled checks | 23 PASS | 0 FAIL ``` - V1/V1b: canonicalization. V2: domain separation. V3: mint-once identity. - V4–V9: frame build and verification steps, including unsigned swarm refusal. - V10: the sealed-artifact profile. - V11: the rev-17 regression suites (erratum `E-1`..`E-23`). The suite uses **fixed inputs**. A live public observation follows it, but is non-gating. Mutable remote state belongs to the estate audit (`realcheck.py`). See [[Conformance and Drift]]. Passing the small vectors proves the byte primitives. It does **not** waive the full trust checks a Consumer owes. ## Fail closed A checker must tell apart **clean**, **drift**, and **not inspected**. A checker that greens because it could not reach a repository has said "no drift" when it means "I did not look." ## Related - [[Implementing the Protocol]] - [[Conformance and Drift]] - [[The Brainstem Kernel]] - [[RAPP CICD]] - [[RAPP Deploy]] - [[RAPP Work]] - [[Failure Atlas]] ======================================================================== FILE: Protocol/Content Addressing.md ======================================================================== --- title: Content Addressing section: Protocol status: published hook: How does rapp/1 hash things, and why is every hash tagged with a space? source: "SPEC.md §5; book/03-content-addressing.md; book/A-reference-manual.md §A.2; conformance/vectors.json (5_hash)" upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Content Addressing In rapp/1, a thing's address is a **hash of its content**. Every hash is **domain-separated**: a short tag naming its purpose is mixed in first. So the same bytes used for two different purposes get two different addresses, and they can never be confused. ## The two hash functions ``` H(space, v) = lowercase_hex( SHA-256( utf8(space) || 0x0A || canonical(v) ) ) ; v a value (§4) Hb(space, b) = lowercase_hex( SHA-256( utf8(space) || 0x0A || b ) ) ; b raw octets ``` - **`H`** hashes a JSON value, after [[Canonicalization]]. - **`Hb`** hashes raw bytes. - The tag (`space`) is followed by one newline byte (`0x0A`), then the content. ## The fixed list of spaces Each tag is used by **exactly one** of the two functions: | Function | Spaces | |---|---| | `H` | `rapp/1:particle`, `rapp/1:wave`, `rapp/1:egg-manifest`, `rapp/1:sealed-aad`, `rapp/1:sealed-key-request` | | `Hb` | `rapp/1:egg`, `rapp/1:rappid`, `rapp/1:grail`, `rapp/1:seal` | An implementation **MUST refuse** to hash under any other tag, or with the wrong function. ## Worked example From the conformance vectors, for the value `{"x": 1}`: | Space | Hash | |---|---| | `H` `rapp/1:particle` | `2ba28c1fad4d0fbea812dddc74f13e3d097099fb07ce621fd208282ade5e5fc3` | | `H` `rapp/1:wave` | `ab18eb8ab68a6093376335930413afb8b92f81a4da863708bbde8e1a875874e8` | | `H` `rapp/1:egg-manifest` | `8c774ac7a755e62e80ce5791f60acc0673212cd05ba5cb1add656e06f58f18aa` | Same value, three spaces, three unrelated addresses. ## Output rules - Always exactly **64 lowercase hex** characters. - **Never truncated. Never uppercased.** - Two values are the same object **iff** their same-space hashes are equal. ## Addresses are pairs - A bare 64-hex string means something **only within its space**. - An implementation **MUST NOT** treat a hash from one space as an object of another. - Content-addressed stores **MUST** key by `(space, hash)`. ## Labels are not identity A `name/X.Y` label is never identity. **Only a hash is.** Names for long-lived things are a separate concept: see [[Identity and the Rappid]]. ## Security assumption SHA-256 collision resistance (FIPS 180-4) is a security assumption of the standard. See [[Security Considerations]]. ## Where these hashes show up - `rapp/1:particle` and `rapp/1:wave` — the two hashes in every frame. See [[The Frame]]. - `rapp/1:rappid` — minting identity tails. See [[Identity and the Rappid]]. - `rapp/1:egg` and `rapp/1:egg-manifest` — packages. See [[The Egg]]. - `rapp/1:grail` — the `grail_id` of a pinned kernel. See [[Distros and Pinning]]. ## Related - [[Canonicalization]] - [[The Frame]] - [[Identity and the Rappid]] - [[The Egg]] - [[Security Considerations]] ======================================================================== FILE: Protocol/Identity and the Rappid.md ======================================================================== --- title: Identity and the Rappid section: Protocol status: published hook: What is a rappid, how is it minted, and when may it ever change? source: "SPEC.md §6; book/04-identity.md; book/A-reference-manual.md §A.3; conformance/vectors.json (6_rappid)" upstream_commit: 0b24e7d60786d39d97265338add9ca784bf5a7ab --- # Identity and the Rappid A **rappid** is the permanent name of a running Brainstem, a door or an object. It is **minted once** and then never changes. It is never computed from the thing's name or content, so renaming or editing never changes who it is. ## The shape ``` rappid:@/:<64 lowercase hex> ``` Example (the stream id used in the conformance frame vectors): ``` rappid:@kody/twin:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ``` - **`owner`** — the **lowercase** GitHub login, 1–39 characters. Display casing is presentation, never identity. - **`slug`** — 1–100 characters. - Both use lowercase letters and digits, with single hyphens between them (no leading, trailing or doubled hyphen). - **`hash`** — exactly 64 lowercase hex characters. Longer parts **MUST** be refused. The grammar is case-sensitive. ## Invalid examples From the conformance vectors, each of these is refused: | Value (tail shortened here) | Problem | |---|---| | `rappid:@Kody/x:aaaa…` | uppercase owner | | `rappid:@kody/x:AAAA…` | uppercase hash | | `rappid:@-kody/x:aaaa…` | leading hyphen | | `rappid:@kody--w/x:aaaa…` | doubled hyphen | | `rappid:v2:kody/x:aaaa…` | legacy form | Legacy forms such as `rappid::`, `rappid:v2:…` and bare UUIDs **MUST** be migrated out, not read forever. ## Minting: exactly once The 64-hex tail is minted once per identity, in one of two ways: - **Keyless:** `tail = Hb("rapp/1:rappid", uuid4_octets)` — the 16 binary octets of a UUIDv4 (RFC 9562). - **Keyed:** `tail = Hb("rapp/1:rappid", SPKI_DER)` — the DER public key (RFC 5280) of the master key. It must be an Ed25519 key or a P-256 (prime256v1) key with an uncompressed point. See [[Content Addressing]] for `Hb` and [[Trust and Signatures]] for keys. ## The one prohibited shortcut A producer **MUST NOT** derive the tail from owner, slug or any name. `sha256("owner/slug")` is explicitly prohibited (drift ID-01/C3). If the tail came from the name, anyone who knew the name could compute the identity. ## Reading an existing identity - On reading a stored `rappid.json`, an implementation **MUST reuse** the stored tail. - It **MUST NOT** re-mint. - `canonicalize_rappid(s)` restructures a legacy form into the current grammar, **keeping the existing hash**. - If the tail is not exactly 64 lowercase hex (for example a legacy 32-hex tail), the result is **provisional**. A provisional id lives only inside the reading process. It must never appear in an emitted frame, `stream_id`, egg or registry entry. ## Re-anchoring: the only re-mint A **re-anchor** mints one fresh tail and records the old id in `_migrated_from`. It is lawful only in these cases: - `upgrade` — a provisional 128-bit id becomes a 256-bit id; - `rotation` — an uncompromised key rotation (the **old** key signs, proving continuity); - `compromise` — a key compromise (a tombstone for the old id is registered in the same append); - `tag-migrate` — a pre-rev-3 keyed tail made with un-tagged `sha256(SPKI)`. A self-asserted `_migrated_from` is **not enough**. The re-anchor must be an owner-signed **re-anchor record** in [[The Registry]]: `{old_rappid, new_rappid, case, utc, sig, old_key_sig?}`. ## Stream ids and kinds A rappid also names streams of [[The Frame|frames]]: - **body stream** — the rappid itself; - **memory stream** — `:`: the full rappid, a colon, then an instance label (lowercase, 1–64 characters); - **swarm stream** — `net: