{ "policy": { "version": 5, "patterns": { "version": 1, "method": "CURATED_PRACTICE_TOPIC", "notice": "Pattern topics identify design choices to practice. Read the ticket's acceptance criteria and justify the simplest suitable approach. Tags are not capability or ownership evidence; an untagged ticket has no curated pattern topic assigned." }, "fieldMix": { "version": 1, "method": "CURATED_ESTIMATE", "notice": "Field percentages are editorial estimates of the ticket's engineering focus. They total 100%; they are not measured time, proficiency scores, or ownership evidence." }, "contentStatus": "PRACTICE_BRIEF", "assessmentStatus": "NOT_QUALIFIED", "evidenceUse": "NONE", "aiPolicy": "AI tools are welcome during implementation. Record assumptions, review the result, and verify its behavior.", "notice": "Fictional engineering practice briefs. Starter repositories, fixtures, automated grading, and verified ownership are not included.", "outcomeEvidence": "Tests, patches, and runbooks are requested deliverables. They become Outcome Evidence only through a qualified Mission and immutable Evidence IDs.", "ownershipEvidence": "Independent adaptation must be observed under a declared verification policy and cite immutable Evidence IDs. Completing a planning ticket establishes no Ownership Evidence." }, "patternTopics": [ { "id": "factory-method", "label": "Factory Method", "group": "Creational" }, { "id": "abstract-factory", "label": "Abstract Factory", "group": "Creational" }, { "id": "builder", "label": "Builder", "group": "Creational" }, { "id": "prototype", "label": "Prototype", "group": "Creational" }, { "id": "singleton", "label": "Singleton", "group": "Creational" }, { "id": "adapter", "label": "Adapter", "group": "Structural" }, { "id": "bridge", "label": "Bridge", "group": "Structural" }, { "id": "composite", "label": "Composite", "group": "Structural" }, { "id": "decorator", "label": "Decorator", "group": "Structural" }, { "id": "facade", "label": "Facade", "group": "Structural" }, { "id": "flyweight", "label": "Flyweight", "group": "Structural" }, { "id": "proxy", "label": "Proxy", "group": "Structural" }, { "id": "chain-of-responsibility", "label": "Chain of Responsibility", "group": "Behavioral" }, { "id": "command", "label": "Command", "group": "Behavioral" }, { "id": "interpreter", "label": "Interpreter", "group": "Behavioral" }, { "id": "iterator", "label": "Iterator", "group": "Behavioral" }, { "id": "mediator", "label": "Mediator", "group": "Behavioral" }, { "id": "memento", "label": "Memento", "group": "Behavioral" }, { "id": "observer", "label": "Observer", "group": "Behavioral" }, { "id": "state", "label": "State", "group": "Behavioral" }, { "id": "strategy", "label": "Strategy", "group": "Behavioral" }, { "id": "template-method", "label": "Template Method", "group": "Behavioral" }, { "id": "visitor", "label": "Visitor", "group": "Behavioral" }, { "id": "ports-and-adapters", "label": "Ports and Adapters", "group": "Architectural" }, { "id": "cqrs", "label": "CQRS", "group": "Architectural" }, { "id": "strangler-fig", "label": "Strangler Fig", "group": "Architectural" }, { "id": "saga", "label": "Saga", "group": "Distributed and reliability" }, { "id": "transactional-outbox", "label": "Transactional Outbox", "group": "Distributed and reliability" }, { "id": "circuit-breaker", "label": "Circuit Breaker", "group": "Distributed and reliability" }, { "id": "bulkhead", "label": "Bulkhead", "group": "Distributed and reliability" } ], "projects": [ { "id": "12ba592f-1c32-4fe8-bb2b-0c964762cf36", "key": "BAPIHOOK", "title": "Public webhook delivery contract", "field": "API design", "summary": "Expose event subscriptions with immutable envelopes, bounded delivery, and safe replay.", "context": "A fictional logistics platform sends shipment events to partner endpoints. Partners need stable schemas and recovery semantics despite duplicate delivery, failures, and subscription changes.", "stack": [ "TypeScript", "OpenAPI", "HTTP", "PostgreSQL" ], "prerequisites": [ "Create a local webhook sender and receiver doubles with synthetic shipment events and disposable signing keys." ], "developerValue": "Practice public event contracts, delivery guarantees, and partner recovery workflows.", "companyValue": "Provide inspectable asynchronous integration behavior with controlled retries and clear compatibility.", "delivery": "Deliver local subscription and delivery contracts; send no external webhook traffic.", "phases": [ { "id": "events", "title": "Define public events", "goal": "Specify immutable identities, schemas, and subscription authority." }, { "id": "deliver", "title": "Deliver predictably", "goal": "Handle signatures, retries, ordering, and endpoint boundaries." }, { "id": "support", "title": "Support evolution and replay", "goal": "Make recovery and schema migration explicit." } ], "tickets": [ { "id": "20fe4bcb-9fe6-4c23-8665-61c27643a24f", "key": "BAPIHOOK-101", "title": "Define immutable webhook envelopes independently of database rows", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "events", "dependsOn": [], "scenario": "Event payloads mirror internal shipment rows and change whenever the schema changes.", "acceptanceCriteria": [ "Publish event ID, type, version, and occurrence time.", "Use a deliberate public payload projection.", "Preserve emitted event bytes or canonical content identity." ], "implementationNotes": [ "Exclude internal fields and hidden operational metadata." ], "verification": [ "Create a documented shipment event.", "Change an internal-only field without altering the public contract." ], "deliverables": [ "Webhook envelope schema." ], "rollout": "Version public payloads before accepting subscriptions.", "skills": [ "Event API design" ], "fieldMix": [ { "field": "API design", "percentage": 80 }, { "field": "Data engineering", "percentage": 20 } ], "patterns": [] }, { "id": "3498cf27-3472-4dae-9044-1f1c9b51984f", "key": "BAPIHOOK-102", "title": "Authorize subscription creation and event scope per organization", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "events", "dependsOn": [ "BAPIHOOK-101" ], "scenario": "A caller can subscribe its endpoint to another organization's shipment events.", "acceptanceCriteria": [ "Derive organization scope from authenticated authority.", "Validate permitted event types.", "Recheck subscription authority before delivery." ], "implementationNotes": [ "Endpoint ownership does not grant access to event data." ], "verification": [ "Create a scoped synthetic subscription.", "Reject foreign-organization event scope and unauthorized event types." ], "deliverables": [ "Subscription authorization boundary." ], "rollout": "Enable subscriptions only after cross-tenant denial checks pass.", "skills": [ "Authorization" ], "fieldMix": [ { "field": "Security", "percentage": 70 }, { "field": "API design", "percentage": 30 } ], "patterns": [] }, { "id": "b492201d-4dae-42e4-8dff-b3265e8ede2d", "key": "BAPIHOOK-103", "title": "Validate webhook destinations through the restricted network boundary", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "events", "dependsOn": [ "BAPIHOOK-102" ], "scenario": "An arbitrary callback URL could direct the sender toward unapproved network resources.", "acceptanceCriteria": [ "Enforce approved schemes, origins, and ports.", "Validate resolution and redirects for every delivery.", "Bind destinations to reviewed subscription revisions." ], "implementationNotes": [ "Use local receiver doubles and an explicit lab allowlist." ], "verification": [ "Deliver to an approved local receiver.", "Reject an unapproved redirect or changed destination authority." ], "deliverables": [ "Webhook destination policy." ], "rollout": "Default to no external destinations until the policy is configured.", "skills": [ "Egress control" ], "fieldMix": [ { "field": "Security", "percentage": 50 }, { "field": "Networking", "percentage": 50 } ], "patterns": [] }, { "id": "495208db-6ee4-4ab1-bed9-2c4674555480", "key": "BAPIHOOK-104", "title": "Sign exact webhook bytes with versioned verification metadata", "type": "TASK", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "deliver", "dependsOn": [ "BAPIHOOK-101", "BAPIHOOK-103" ], "scenario": "Partners cannot verify signatures after the sender serializes the same event differently on retry.", "acceptanceCriteria": [ "Sign the exact delivered bytes.", "Include key identity and bounded timestamp semantics.", "Document receiver verification before payload trust." ], "implementationNotes": [ "Use generated test keys and never log signing material." ], "verification": [ "Verify a valid local delivery.", "Change one byte or timestamp and reject verification." ], "deliverables": [ "Signing contract and receiver example." ], "rollout": "Introduce a versioned signature format with a bounded rotation overlap.", "skills": [ "Webhook security" ], "fieldMix": [ { "field": "Security", "percentage": 70 }, { "field": "API design", "percentage": 30 } ], "patterns": [] }, { "id": "5f29b50b-ca3a-42f8-ad42-13b6a4f27e21", "key": "BAPIHOOK-105", "title": "Document at-least-once delivery with stable event identities", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "deliver", "dependsOn": [ "BAPIHOOK-104" ], "scenario": "The platform advertises one delivery even though connection loss can cause duplicates.", "acceptanceCriteria": [ "Keep event identity stable across attempts.", "Record delivery attempts separately from event facts.", "Provide a receiver deduplication example." ], "implementationNotes": [ "Do not claim exactly-once delivery across HTTP." ], "verification": [ "Lose a receiver acknowledgement and retry.", "Verify the receiver applies the event once using its deduplication record." ], "deliverables": [ "Delivery semantics and replay checks." ], "rollout": "Preserve event identity through all retries and support actions.", "skills": [ "Distributed systems", "Idempotency" ], "fieldMix": [ { "field": "Distributed systems", "percentage": 60 }, { "field": "API design", "percentage": 40 } ], "patterns": [] }, { "id": "2fdf96a5-bf08-4ffa-b951-76ac55377094", "key": "BAPIHOOK-106", "title": "Bound retry scheduling and distinguish terminal receiver responses", "type": "TASK", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "deliver", "dependsOn": [ "BAPIHOOK-105" ], "scenario": "The sender retries every response indefinitely, including malformed-endpoint failures.", "acceptanceCriteria": [ "Define retryable status classes and total delivery age.", "Respect bounded retry-after guidance.", "Move exhausted deliveries to an inspectable terminal state." ], "implementationNotes": [ "Use an injected clock and fixed maximum attempts." ], "verification": [ "Recover from a temporary receiver failure.", "Exhaust a persistent failure without unbounded work." ], "deliverables": [ "Retry contract." ], "rollout": "Start with conservative limits; expose terminal state to authorized subscription owners.", "skills": [ "Retry policy" ], "fieldMix": [ { "field": "Site reliability", "percentage": 50 }, { "field": "API design", "percentage": 30 }, { "field": "Integrations", "percentage": 20 } ], "patterns": [] }, { "id": "564011eb-ab74-4ab5-9158-29ea7794028e", "key": "BAPIHOOK-107", "title": "Expose event ordering limits without requiring global sequencing", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "deliver", "dependsOn": [ "BAPIHOOK-105", "BAPIHOOK-106" ], "scenario": "Partners assume events arrive in the order they happened, but parallel delivery reorders them.", "acceptanceCriteria": [ "Declare the actual ordering scope.", "Include resource revision where needed for stale-event handling.", "Document how receivers handle gaps and older revisions." ], "implementationNotes": [ "Avoid promising global ordering without implementing it." ], "verification": [ "Deliver two resource revisions out of order.", "Verify a receiver preserves its declared monotonic state." ], "deliverables": [ "Ordering contract and receiver tests." ], "rollout": "Publish ordering guidance before increasing delivery parallelism.", "skills": [ "Event ordering" ], "fieldMix": [ { "field": "Distributed systems", "percentage": 60 }, { "field": "API design", "percentage": 40 } ], "patterns": [] }, { "id": "0c8052d6-7329-40c0-9022-5ed24d6d9900", "key": "BAPIHOOK-108", "title": "Replay terminal deliveries without mutating original event content", "type": "STORY", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "support", "dependsOn": [ "BAPIHOOK-106", "BAPIHOOK-107" ], "scenario": "Support repairs a payload during replay and leaves the same event ID representing different facts.", "acceptanceCriteria": [ "Replay the original immutable event under a new attempt identity.", "Require authorized subscription scope and reason.", "Reject replay when current destination or data authority is revoked." ], "implementationNotes": [ "Corrections require a new event identity and explicit relation." ], "verification": [ "Replay a failed synthetic delivery.", "Reject changed payload bytes and revoked subscription authority." ], "deliverables": [ "Audited replay endpoint." ], "rollout": "Keep replay bounded and visible to subscription owners.", "skills": [ "Auditability", "Immutability" ], "fieldMix": [ { "field": "API design", "percentage": 40 }, { "field": "Security", "percentage": 30 }, { "field": "Data engineering", "percentage": 30 } ], "patterns": [] }, { "id": "36d11b9f-244f-47ec-9e56-12816d9fb58f", "key": "BAPIHOOK-109", "title": "Design webhook schema migration for independently deployed receivers", "type": "TASK", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 300, "phaseId": "support", "dependsOn": [ "BAPIHOOK-104", "BAPIHOOK-107", "BAPIHOOK-108" ], "scenario": "A required payload change cannot be safely deployed to all partner receivers at once.", "acceptanceCriteria": [ "Compare versioned subscriptions and additive-compatible evolution.", "Define supported version overlap and retirement evidence.", "Rehearse receiver upgrade, rollback, and replay of historical events." ], "implementationNotes": [ "Historical events retain their original schema identity." ], "verification": [ "Upgrade one synthetic receiver while another stays legacy.", "Replay an old event after upgrade and verify documented handling." ], "deliverables": [ "Webhook evolution decision record." ], "rollout": "Keep supported schema serializers and examples through the retention window.", "skills": [ "API lifecycle", "Compatibility" ], "fieldMix": [ { "field": "API design", "percentage": 60 }, { "field": "System design", "percentage": 40 } ], "patterns": [] }, { "id": "62fabe0d-08af-453d-9dc5-dff2b45599c2", "key": "BAPIHOOK-110", "title": "Publish a webhook receiver checklist with failure recovery", "type": "CHORE", "priority": "LOW", "difficulty": "FOUNDATIONAL", "estimateMinutes": 90, "phaseId": "support", "dependsOn": [ "BAPIHOOK-109" ], "scenario": "Partners acknowledge before persisting event identity and lose events after a crash.", "acceptanceCriteria": [ "Show signature verification before parsing trusted fields.", "Persist deduplication and accepted work before acknowledgement.", "Document retry, replay, and unknown-version behavior." ], "implementationNotes": [ "Use the local receiver double and synthetic events." ], "verification": [ "Recover after a receiver crash before acknowledgement.", "Reject an unsupported event version without discarding its identity." ], "deliverables": [ "Executable receiver guide." ], "rollout": "Version the guide with event and signature contracts.", "skills": [ "Documentation", "Integration design" ], "fieldMix": [ { "field": "Integrations", "percentage": 40 }, { "field": "Security", "percentage": 30 }, { "field": "Distributed systems", "percentage": 30 } ], "patterns": [] } ] } ] }