<!-- Generated from governed source; do not edit. -->

Source: Koko-os advanced program v0.1.0; commit e8416fd254dc300caa65b0d042309baa98864012; package SHA-256 90c538e5ec377f9bd6eb2347b19240c2ba959624e05ff868ee34c7edabaa68d8; binding commit_verified.

# OpenAI Architect Foundations — workbook

Use synthetic data. Record your own evidence and ask a reviewer to assess it; this workbook does not award a credential.

## AF-1: Architecture and orchestration

A nonprofit reviews synthetic grant packets. Ingest and final approval are fixed; evidence gathering varies by packet. Team capacity is limited and cross-tenant disclosure is unacceptable.

### Starter

Requirements: authorized read-only search; human approval for publication; traceable evidence; variable packet formats. Candidates: deterministic workflow; single agent with fixed gates; specialist agents. Runtime candidates: direct Responses, Agents SDK, managed Agents API. No measured latency or cost yet.

### Tasks

- [ ] Draw all three execution designs and label control owners.
- [ ] Create a comparison matrix distinguishing documented capabilities, assumptions, and measurements.
- [ ] Select one design and runtime; state a falsifiable trigger for revisiting each.
- [ ] Walk through missing evidence and a cross-tenant search proposal.

### Deliverables

- Workflow diagram and boundary owners
- Decision matrix and ADR
- Two failure traces and a reconsideration trigger

### Failure and challenge cases

- Challenge: the evidence source changes after review but before execution; revise the design and explain its new outcome.
- A dependency returns malformed data or times out; show the safe state and owner of recovery.
- A handoff arrives without verified tenant identity; stop and trace the ownership and recovery decision.

### Evidence and reviewer notes

[Write your evidence, results, limitations and review notes here.]

### Rubric

- **Boundary and ownership:** Names actors, ownership, trusted inputs and enforcement at every consequential transition. Failure: Delegates authorization or approval to the model.
- **Evidence and alternatives:** Compares competing designs using explicit assumptions, constraints and inspectable artifacts. Failure: Presents an unsupported choice as a measured fact.
- **Failure and transfer:** Traces the specified negative cases, states expected outcomes, and revises the design for the challenge. Failure: Ignores failures, duplicate effects, or evidence gaps.

## AF-2: Tools, MCP and trust boundaries

A model can search synthetic tenant records and propose publication. The action service can time out after accepting a request.

### Starter

search(caseId, tenantId) -> documents; publish(caseId, packetVersion) -> status. Current design trusts model tenantId and retries publish on any timeout.

### Tasks

- [ ] Draw the actors and trust boundaries.
- [ ] Rewrite contracts with authenticated identity, authorized scope, typed failures, and audit fields.
- [ ] Bind approval to action, packet version and expiry; specify duplicate handling.
- [ ] Trace forged tenant, expired approval, and ambiguous timeout.

### Deliverables

- Boundary diagram and tool contracts
- Approval and idempotency state table
- Negative traces

### Failure and challenge cases

- Challenge: the evidence source changes after review but before execution; revise the design and explain its new outcome.
- A dependency returns malformed data or times out; show the safe state and owner of recovery.
- A duplicate approved action is delivered with changed parameters; reject the mismatch and preserve the audit record.

### Evidence and reviewer notes

[Write your evidence, results, limitations and review notes here.]

### Rubric

- **Boundary and ownership:** Names actors, ownership, trusted inputs and enforcement at every consequential transition. Failure: Delegates authorization or approval to the model.
- **Evidence and alternatives:** Compares competing designs using explicit assumptions, constraints and inspectable artifacts. Failure: Presents an unsupported choice as a measured fact.
- **Failure and transfer:** Traces the specified negative cases, states expected outcomes, and revises the design for the challenge. Failure: Ignores failures, duplicate effects, or evidence gaps.

## AF-3: Codex configuration and delivery architecture

A coding agent is asked to add a negative authorization test in a synthetic repository; no production deployment is in scope.

### Starter

Save the following as test_policy.py and run `python3 -m unittest -v test_policy`. The test passes even though the intentionally broken guard lets tenant A read tenant B. Only synthetic identifiers are used.

```python
import unittest

def can_read(principal_tenant, record_tenant):
    return principal_tenant == principal_tenant  # intentionally broken

class TestAccess(unittest.TestCase):
    def test_access_returns_a_boolean(self):
        self.assertIsInstance(can_read("tenant-a", "tenant-b"), bool)

if __name__ == "__main__":
    unittest.main()
```

Repository guidance for the exercise: run the package tests and never commit credentials. A nested package instruction identifies the policy tests. No production deployment is authorized.

### Tasks

- [ ] Map instruction discovery and identify uncertainty to verify in the actual environment.
- [ ] Save the starter and run its existing test; record why its green result does not establish isolation.
- [ ] Change the test to assert that tenant A cannot read tenant B and confirm the intentionally broken guard now fails. Fix the guard to compare the two tenant IDs; rerun and record the passing result.
- [ ] Define workspace, tool, credential and network scope, then describe CI, human review, exact commands and any remaining verification gaps.

### Deliverables

- Instruction and permission map
- Saved test file, failing-before and passing-after command output
- CI and human review handoff with limitations

### Failure and challenge cases

- Challenge: the evidence source changes after review but before execution; revise the design and explain its new outcome.
- A dependency returns malformed data or times out; show the safe state and owner of recovery.
- A deliberately broken tenant guard still passes the test; repair the test and show the failure before restoring the guard.

### Evidence and reviewer notes

[Write your evidence, results, limitations and review notes here.]

### Rubric

- **Boundary and ownership:** Names actors, ownership, trusted inputs and enforcement at every consequential transition. Failure: Delegates authorization or approval to the model.
- **Evidence and alternatives:** Compares competing designs using explicit assumptions, constraints and inspectable artifacts. Failure: Presents an unsupported choice as a measured fact.
- **Failure and transfer:** Traces the specified negative cases, states expected outcomes, and revises the design for the challenge. Failure: Ignores failures, duplicate effects, or evidence gaps.

## AF-4: Context, retrieval and output contracts

A policy reviewer must answer from a synthetic corpus containing current, superseded, and tenant-restricted records.

### Starter

Corpus: P1 v1 superseded; P1 v2 current; P2 belongs to tenant B. Request: tenant A asks for the current rule. Budget must include instructions, request, evidence, response, and margin.

### Tasks

- [ ] Allocate a context budget and specify truncation and freshness behavior.
- [ ] Define authorized retrieval metadata and source lineage.
- [ ] Design an output schema and separate semantic checks.
- [ ] Trace stale source, invented citation, missing evidence and cross-tenant retrieval.

### Deliverables

- Context budget and lifecycle
- Retrieval and citation contract
- Schema and four negative traces

### Failure and challenge cases

- Challenge: the evidence source changes after review but before execution; revise the design and explain its new outcome.
- A dependency returns malformed data or times out; show the safe state and owner of recovery.
- A schema-valid answer cites a source outside the authorized retrieval record; reject it and seek evidence.

### Evidence and reviewer notes

[Write your evidence, results, limitations and review notes here.]

### Rubric

- **Boundary and ownership:** Names actors, ownership, trusted inputs and enforcement at every consequential transition. Failure: Delegates authorization or approval to the model.
- **Evidence and alternatives:** Compares competing designs using explicit assumptions, constraints and inspectable artifacts. Failure: Presents an unsupported choice as a measured fact.
- **Failure and transfer:** Traces the specified negative cases, states expected outcomes, and revises the design for the challenge. Failure: Ignores failures, duplicate effects, or evidence gaps.

## AF-5: Reliability, evaluation and resource tradeoffs

A synthetic review workflow pauses for approval, then calls a publication stub that may time out after accepting the action.

### Starter

Fixtures: normal, no evidence, conflicting policy, tenant mismatch, expired approval, duplicate request, accepted-but-timeout. No live model or provider costs are measured.

### Tasks

- [ ] Write the workflow state machine with durable identifiers.
- [ ] Define retry, cancellation, approval revalidation and reconciliation.
- [ ] Build a frozen evaluation plan with control gates and human-reviewed quality slices.
- [ ] Compare candidate designs using stated assumptions and define rollout and rollback triggers.

### Deliverables

- State and recovery table
- Frozen evaluation and critical gates
- Tradeoff and rollback record

### Failure and challenge cases

- Challenge: the evidence source changes after review but before execution; revise the design and explain its new outcome.
- A dependency returns malformed data or times out; show the safe state and owner of recovery.
- A workflow is canceled after a write was dispatched; prevent new effects and reconcile the dispatched action.

### Evidence and reviewer notes

[Write your evidence, results, limitations and review notes here.]

### Rubric

- **Boundary and ownership:** Names actors, ownership, trusted inputs and enforcement at every consequential transition. Failure: Delegates authorization or approval to the model.
- **Evidence and alternatives:** Compares competing designs using explicit assumptions, constraints and inspectable artifacts. Failure: Presents an unsupported choice as a measured fact.
- **Failure and transfer:** Traces the specified negative cases, states expected outcomes, and revises the design for the challenge. Failure: Ignores failures, duplicate effects, or evidence gaps.
