{ "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": "29a64a20-2cb2-41f8-afc9-8685fde8b8b0", "key": "BAPIPAGE", "title": "Consistent query and pagination API", "field": "API design", "summary": "Expose a changing catalog through bounded filters, stable cursors, and explicit consistency.", "context": "A fictional logistics platform lists shipments for partner dashboards. Offset pagination duplicates records during updates, while unrestricted filters create expensive database queries.", "stack": [ "TypeScript", "OpenAPI", "PostgreSQL" ], "prerequisites": [ "Create a local shipment dataset with synthetic tenants, equal timestamps, and concurrent update fixtures." ], "developerValue": "Practice cursor design, query contracts, and consistency/performance tradeoffs.", "companyValue": "Provide predictable list APIs that remain bounded and preserve tenant scope.", "delivery": "Deliver a local versioned listing endpoint and documented client iteration behavior.", "phases": [ { "id": "query", "title": "Define query semantics", "goal": "Specify supported filters, sorting, and authorization." }, { "id": "cursor", "title": "Implement stable traversal", "goal": "Bind cursors and handle concurrent data changes." }, { "id": "review", "title": "Review contract limits", "goal": "Measure query plans and document consistency." } ], "tickets": [ { "id": "8e05903c-9a17-41d1-be86-e6d7d3d9eaed", "key": "BAPIPAGE-101", "title": "Define supported shipment filters and their exact semantics", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "query", "dependsOn": [], "scenario": "Different clients interpret date ranges and empty status lists differently.", "acceptanceCriteria": [ "Specify inclusive and exclusive boundaries.", "Distinguish absent from empty filters.", "Reject unsupported filter properties." ], "implementationNotes": [ "Use UTC instants for timestamp filters." ], "verification": [ "Exercise a boundary timestamp.", "Reject an empty status list if the contract declares it invalid." ], "deliverables": [ "Filter contract." ], "rollout": "Publish explicit examples before replacing legacy behavior.", "skills": [ "API design" ], "fieldMix": [ { "field": "API design", "percentage": 100 } ], "patterns": [] }, { "id": "b8e92724-56d7-4d2e-85ef-c7768dd0c094", "key": "BAPIPAGE-102", "title": "Validate bounded sort options instead of accepting SQL fragments", "type": "TASK", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "query", "dependsOn": [ "BAPIPAGE-101" ], "scenario": "Clients can pass arbitrary sort expressions into query construction.", "acceptanceCriteria": [ "Allowlist sort fields and directions.", "Use parameterized query construction.", "Append a stable unique tie-breaker." ], "implementationNotes": [ "Never concatenate untrusted SQL." ], "verification": [ "Sort equal timestamps deterministically.", "Reject an expression-shaped sort value." ], "deliverables": [ "Safe sort parser." ], "rollout": "Adopt on the new endpoint first; keep unknown sorts rejected.", "skills": [ "Input validation", "SQL" ], "fieldMix": [ { "field": "Database engineering", "percentage": 40 }, { "field": "Security", "percentage": 40 }, { "field": "API design", "percentage": 20 } ], "patterns": [] }, { "id": "969006e0-82f1-47b6-863c-c7a6bacc4c99", "key": "BAPIPAGE-103", "title": "Enforce tenant scope before applying user filters", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 150, "phaseId": "query", "dependsOn": [ "BAPIPAGE-102" ], "scenario": "An optional organization filter can replace the caller's tenant predicate.", "acceptanceCriteria": [ "Derive tenant from authenticated context.", "Apply scope in repository queries.", "Keep client filters unable to widen authority." ], "implementationNotes": [ "Unauthorized records must not influence totals." ], "verification": [ "List owned shipments with several filters.", "Attempt foreign-tenant filtering and verify non-disclosure." ], "deliverables": [ "Scoped query repository." ], "rollout": "Gate all listing variants on cross-tenant denial checks.", "skills": [ "Authorization" ], "fieldMix": [ { "field": "Security", "percentage": 70 }, { "field": "Database engineering", "percentage": 30 } ], "patterns": [] }, { "id": "10c1fef9-3575-4332-9126-c8cacfa0d8f0", "key": "BAPIPAGE-104", "title": "Encode opaque cursors bound to the normalized query", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "cursor", "dependsOn": [ "BAPIPAGE-101", "BAPIPAGE-102", "BAPIPAGE-103" ], "scenario": "A cursor from one status filter is reused with another and skips records.", "acceptanceCriteria": [ "Bind cursor to tenant, sort, filter digest, and position.", "Validate schema, size, integrity, and expiry.", "Return a stable invalid-cursor problem." ], "implementationNotes": [ "Opaque encoding alone is not integrity protection." ], "verification": [ "Continue a matching query.", "Reject tampered, expired, and cross-query cursors." ], "deliverables": [ "Cursor contract." ], "rollout": "Version cursors and retain support only for declared compatible versions.", "skills": [ "Cursor design", "Integrity" ], "fieldMix": [ { "field": "API design", "percentage": 50 }, { "field": "Security", "percentage": 30 }, { "field": "Database engineering", "percentage": 20 } ], "patterns": [] }, { "id": "f21744ab-3606-40e0-998f-d2dadd762010", "key": "BAPIPAGE-105", "title": "Use keyset traversal for shipments sharing timestamps", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "cursor", "dependsOn": [ "BAPIPAGE-104" ], "scenario": "Pagination drops shipments when several rows have the same update timestamp.", "acceptanceCriteria": [ "Compare the complete sort tuple.", "Use the unique tie-breaker consistently in both directions.", "Avoid duplicate boundary rows." ], "implementationNotes": [ "Indexes must match the declared ordering." ], "verification": [ "Traverse a fixture with many equal timestamps.", "Verify no omission or duplication at page boundaries." ], "deliverables": [ "Keyset query implementation." ], "rollout": "Compare full traversal against a fixed fixture before replacing offsets.", "skills": [ "Database queries" ], "fieldMix": [ { "field": "Database engineering", "percentage": 70 }, { "field": "API design", "percentage": 30 } ], "patterns": [] }, { "id": "f6304386-0c3e-4f2e-a8c6-8f4705f20045", "key": "BAPIPAGE-106", "title": "Define how mutable shipment updates affect an active traversal", "type": "TASK", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 300, "phaseId": "cursor", "dependsOn": [ "BAPIPAGE-105" ], "scenario": "A shipment changes status between pages, and partners expect a snapshot the endpoint never promised.", "acceptanceCriteria": [ "Compare live traversal, snapshot boundary, and export-resource options.", "Choose explicit consistency semantics for this endpoint.", "Document duplicate or omission risks that remain." ], "implementationNotes": [ "Do not claim snapshot consistency without implementing its data boundary." ], "verification": [ "Update a shipment between pages under the chosen model.", "Verify observed behavior matches the documented guarantee." ], "deliverables": [ "Pagination consistency decision record." ], "rollout": "Introduce the consistency contract before clients depend on stable exports.", "skills": [ "Consistency", "API architecture" ], "fieldMix": [ { "field": "System design", "percentage": 40 }, { "field": "API design", "percentage": 40 }, { "field": "Database engineering", "percentage": 20 } ], "patterns": [] }, { "id": "c7d39be5-e77a-4148-888f-82efe5e0018a", "key": "BAPIPAGE-107", "title": "Bound total-count work independently of result pagination", "type": "TASK", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "cursor", "dependsOn": [ "BAPIPAGE-103", "BAPIPAGE-105" ], "scenario": "A fast first page still waits for an expensive exact count.", "acceptanceCriteria": [ "Make count behavior explicit and optional if appropriate.", "Bound count execution time.", "Distinguish unavailable or estimated totals from exact totals." ], "implementationNotes": [ "Never label an estimate as an exact count." ], "verification": [ "Return a page without optional count work.", "Timeout count calculation without misreporting zero results." ], "deliverables": [ "Count contract." ], "rollout": "Default to the least expensive contract satisfying the use case.", "skills": [ "Query performance" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 50 }, { "field": "Database engineering", "percentage": 30 }, { "field": "API design", "percentage": 20 } ], "patterns": [] }, { "id": "a0857ffa-6b96-4052-b918-837c0d51d625", "key": "BAPIPAGE-108", "title": "Review query plans for supported high-cardinality filters", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 240, "phaseId": "review", "dependsOn": [ "BAPIPAGE-105", "BAPIPAGE-107" ], "scenario": "A permitted filter scans every shipment despite bounded page size.", "acceptanceCriteria": [ "Capture plans against a declared synthetic dataset.", "Check indexes for supported filter/sort combinations.", "Report dataset size, cache state, and machine limits." ], "implementationNotes": [ "Local query plans are evidence for the fixture, not production latency guarantees." ], "verification": [ "Measure a selective and broad query.", "Identify a missing-index case and compare the corrected plan." ], "deliverables": [ "Query-plan review." ], "rollout": "Add indexes through migrations; retain a rollback plan for index changes.", "skills": [ "PostgreSQL", "Performance" ], "fieldMix": [ { "field": "Database engineering", "percentage": 60 }, { "field": "Performance engineering", "percentage": 40 } ], "patterns": [] }, { "id": "3fc7f3ef-5274-463c-b930-955e06e39eed", "key": "BAPIPAGE-109", "title": "Provide a resumable iterator that stops on cursor expiry", "type": "STORY", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "review", "dependsOn": [ "BAPIPAGE-104", "BAPIPAGE-106", "BAPIPAGE-108" ], "scenario": "The client SDK retries invalid cursors forever instead of telling callers to restart.", "acceptanceCriteria": [ "Expose bounded async iteration with cancellation.", "Stop on terminal and invalid-cursor responses.", "Document restart behavior under the consistency contract." ], "implementationNotes": [ "Do not silently restart and merge potentially duplicated records." ], "verification": [ "Iterate a complete synthetic result set.", "Expire a cursor mid-run and surface the documented error." ], "deliverables": [ "Client iterator example." ], "rollout": "Release with explicit cursor-lifecycle documentation.", "skills": [ "SDK design" ], "fieldMix": [ { "field": "Developer tooling", "percentage": 60 }, { "field": "API design", "percentage": 40 } ], "patterns": [] }, { "id": "17b76fdd-5a75-4be1-a6d5-3aab9bc64212", "key": "BAPIPAGE-110", "title": "Document list versus export guarantees for partner dashboards", "type": "CHORE", "priority": "LOW", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "review", "dependsOn": [ "BAPIPAGE-109" ], "scenario": "Partners use an interactive list endpoint as if it were a financial or audit export.", "acceptanceCriteria": [ "State ordering, freshness, and traversal guarantees.", "List unsupported snapshot assumptions.", "Show the appropriate restart and bounded export approach." ], "implementationNotes": [ "No legal or financial completeness claims." ], "verification": [ "Follow the guide for a changing dashboard list.", "Identify a use case requiring a separate snapshot export." ], "deliverables": [ "Query API usage guide." ], "rollout": "Keep examples aligned with implemented consistency behavior.", "skills": [ "Technical writing" ], "fieldMix": [ { "field": "API design", "percentage": 100 } ], "patterns": [] } ] } ] }