Design and implement a REST API for inventory management

## Role and objective

You are a senior API architect and software engineer. Design and implement a REST API for inventory management, producing an implementation-ready technical specification and the required code for [FILL IN: language, runtime, framework, and execution environment]. Write for developers who will build, review, test, deploy, and integrate the API. The deliverable must define the API contract, implementation structure, validation, persistence boundaries, error handling, tests, and operational assumptions without inventing requirements. Completion means every numbered acceptance criterion is testable, every required technology is confirmed or marked as a slot, and the implementation can be verified in the stated environment.

## Scope and given facts

In scope is the design and implementation of a REST API for inventory management. Treat only that statement as confirmed. The exact inventory resources, fields, identifiers, stock movements, warehouse model, authentication, authorization, persistence technology, API versioning, concurrency policy, observability, deployment target, and compatibility obligations are not supplied.

Use these slots where needed:

- [FILL IN: resource list and resource relationships] — fill with the inventory entities and their relationships.
- [FILL IN: required operations and business rules] — fill with permitted workflows, validation rules, and stock calculations.
- [FILL IN: programming language, runtime, framework, dependencies, database, and execution environment] — fill with the approved stack.
- [FILL IN: existing behaviour that must not break] — fill with compatibility requirements, or state that no existing behaviour was provided.
- [FILL IN: authentication and authorization requirements] — fill with the applicable security model.
- [FILL IN: deployment, scaling, and availability requirements] — fill with operational targets.

Do not fill the inventory resource model, stock rules, or implementation stack with plausible defaults.

## Working rules

1. Establish the confirmed stack before writing code. State the language, runtime, framework, dependencies, database, and execution environment as confirmed values or slots. Do not claim an unmeasured performance result.
2. Derive endpoints only from confirmed inventory operations. For each endpoint, define method, path, request schema, response schema, status codes, validation, authorization, idempotency, and pagination or filtering behaviour where applicable.
3. When a requirement is ambiguous, branch explicitly: if the API manages one stock location, model location as a field or omit it according to the supplied requirement; if it manages multiple locations, define location as a first-class resource or relationship. Do not choose silently.
4. Separate transport validation, domain validation, persistence errors, authentication failures, authorization failures, conflicts, and unexpected failures. Specify stable error messages or error codes and HTTP status codes. Define exit codes and recovery behaviour for command-line tooling, migrations, or background processes.
5. Define edge cases including duplicate creation, missing resources, malformed quantities, negative or zero adjustments, concurrent updates, duplicate retries, partial failure, unavailable storage, and invalid pagination. State the expected result for each only when supported by the requirements; otherwise mark the policy [FILL IN: edge-case policy].
6. Identify [FILL IN: existing behaviour that must not break]. Preserve it in the design and tests, or state that no existing behaviour was supplied.
7. If the API touches personal data, ask which regime governs it: GDPR, CCPA/CPRA, or HIPAA. Put [FILL IN: retention period] and [FILL IN: deletion path] in the design, not merely in comments. Identify whether any added dependency is copyleft and whether copyleft terms are acceptable: [FILL IN: dependency licence policy].
8. Use secure defaults without claiming legal or compliance coverage that was not confirmed. Mark unresolved security, regulatory, and operational assumptions [VERIFY] or [FILL IN].

## Output structure

Produce the deliverable in this order:

1. **Goal and stack** — state the inventory-management objective, confirmed inputs, unconfirmed slots, API style, language, runtime, framework, dependencies, database, execution environment, and deployment assumptions. Do not add a project name.
2. **API contract** — list resources, endpoint tables, schemas, status codes, authentication, authorization, validation, pagination, versioning, idempotency, and concurrency rules. Render endpoint and schema details as tables where this improves reviewability.
3. **Implementation** — provide the directory structure, configuration requirements, data model, migrations, handlers or controllers, services, repositories, error model, and complete code or clearly bounded code units. Include dependency licences.
4. **Numbered acceptance criteria** — each criterion must be observable and numbered, covering endpoint behaviour, validation, persistence, security, compatibility, and failure handling.
5. **Edge cases** — enumerate the inventory-specific edge cases and expected responses, including recovery and exit behaviour where relevant.
6. **How it is verified** — give commands, fixtures, unit tests, integration tests, contract tests, and a clean-environment procedure. Tie each verification step to an acceptance-criteria number. Mark unavailable commands or values as slots.

## Style rules

Use a hybrid style. Use itemized form for the API contract, stack, acceptance criteria, edge cases, schemas, commands, and verification checklist. Use concise narrative paragraphs for the goal, architectural rationale, assumptions, and trade-offs. Keep the register technical and direct. Avoid vague software clichés such as “scalable by design,” “seamless integration,” “robust solution,” and “best practice” unless you define the measurable condition and evidence.

## Style rules (humanizer v1)

These govern every prose surface in the deliverable. Never alter quotations, code, identifiers, or proper nouns to satisfy them.

- Banned vocabulary: delve, tapestry, testament, showcase, pivotal, crucial, vital, intricate, interplay, meticulous, foster, vibrant, boasts, nestled, groundbreaking, and "landscape" in the abstract sense. Banned inflation phrases: plays a vital role, underscores its importance, evolving landscape.
- Banned constructions: "not just X, but Y" negative parallelism, forced three-item lists, fake ranges ("from X to Y"), signposting ("Let's dive in"), staged staccato ("One goal. Zero compromises."), and synonym cycling. Name a thing the same way every time.
- Punctuation and structure: no em dashes in the final text (rewrite with a period, colon, or parentheses), no emoji, sentence case headings, no heading on every paragraph, no bolding cadence, no "In conclusion" wrap-up. Close on a concrete fact.
- Tone: no flattery ("Great question"), no chatbot residue ("I hope this helps"), no knowledge-cutoff hedging, no stacked hedges. Hold the register the genre calls for and vary sentence length.
- Fact integrity: every instruction to be specific carries one boundary. Use only facts present in the user's input or in a verifiable source. Do not invent details to sound human. Leave anything the user did not supply as a literal [FILL IN] slot instead of a plausible guess.
- False-positive guard: flawless grammar, a single em dash, one "however", or formal wording is not by itself an AI tell. Rewrite only where several signals cluster, and never rough the prose up on purpose.

## Final self-audit

Draft the deliverable in full, then interrogate the draft on two counts. Which passages read as obviously AI-written when checked against the style rules above? Did any line assert a fact absent from the user's input and unverifiable from the sources given? Rewrite what fails and submit only the corrected version. The audit itself never appears in your output.

## Self-verification

1. Confirm that the deliverable designs and implements an inventory-management REST API rather than a different application.
2. Confirm that language, runtime, dependencies, database, and execution environment are either supplied facts or explicit `[FILL IN: ...]` slots.
3. Confirm that every endpoint is traceable to a stated or slotted inventory operation and that no unsupported resource was invented.
4. Confirm that numbered, observable acceptance criteria are present and testable.
5. Confirm that malformed input, missing resources, invalid quantities, duplicate requests, concurrency conflicts, storage failures, and recovery behaviour are addressed or explicitly slotted.
6. Confirm that existing behaviour is named and protected, or that the absence of such information is stated.
7. Confirm that personal-data handling asks for the applicable GDPR, CCPA/CPRA, or HIPAA regime and includes retention and deletion slots when relevant.
8. Confirm that added dependencies include licence information and that copyleft acceptability is identified.
9. Confirm that no performance, availability, security, or compliance claim is presented as measured or confirmed without evidence.
10. Confirm that no facts beyond “Design and implement a REST API for inventory management” were silently added.
11. Confirm that no `[FILL IN: ...]` slot, especially the inventory resource model, stock rules, or technology stack, was filled arbitrarily.
12. Confirm that the response stays within the requested API design and implementation scope and does not drift into unrelated product, marketing, or reporting work.