# Specialist Report — agent-feature (PAPI spec `20260626-123209-agent-feature.md`)

## Outcome

**No code changes were made in this repo (`platform-api` / api2). This is the correct, intended outcome for this spec — not a skipped or incomplete task.**

The spec describes a **DB-schema-only change**: add a per-project composite
`UNIQUE (ProjectShardId, Name)` constraint to 5 tables (AssetType, SystemType,
Asset, CommissioningSystem, CommissioningWorkflow). That constraint lives in the
**Postgres schema repository**, not in this API repo.

## Files changed

| File | Change |
|------|--------|
| `docs/specs/20260626-123209-agent-feature.md` | Added a **Decisions** section documenting why no API2 changes were made. |
| `_SPECIALIST_REPORT.md` | This report. |

No source files under `src/`, no validators, controllers, routes, services, or
tests were added or modified — by design.

## Why no API2 work (evidence)

The spec is explicit and self-consistent on this point:

- **Goal**: *"DB-schema-only change owned by the Postgres repo; no API1/API2 code changes."*
- **Behavior changes (the approved plan's API2 changes, verbatim)**: `none`
- **Out of scope**: *"Any API1 or API2 code changes (DB-schema-only change)"*
- **`files:` frontmatter**: `(none listed)`

Repo investigation independently confirmed the spec is right:

1. **This repo owns no DB schema.** There are no migrations, no `CREATE TABLE`,
   no `ALTER TABLE`, no constraint DDL in `src/`. The Postgres schema is
   externally managed via Liquibase. `docker/distributed_changelog_local.xml`
   references `PostgreSQLDatabase/Database/xyz/Tables/` and
   `PostgreSQLDatabase/Database/xyz/Constraints/` — directories that **do not
   exist in this repo**. The only `.sql` files here are
   `docker/db-create.sql` (role/extension only) and a test-data dump. A UNIQUE
   constraint therefore cannot be added here.

2. **The 5 affected entities do not exist in `master` source.** AssetType,
   SystemType, Asset, CommissioningSystem, and CommissioningWorkflow have **zero
   matches in `src/` on `master`**. They appear only on unmerged feature
   branches (e.g. `PAPI-ASSET-...`, `AI-AGENT-TEST-3-...`). Consequently there is
   no create/insert endpoint on `master` whose behavior a new `Name` uniqueness
   constraint could change, and nothing to test end-to-end here.

Fabricating endpoints/services to satisfy a generic "implement the full API2
surface" instruction would have directly violated the spec's **Out of scope**
clause and added unwanted code to a repo that does not own the schema.

## Deviations from the spec

None. The implemented outcome (no API2 changes) matches the spec's
`Behavior changes: none` and empty `files:` list.

## Acceptance criteria status

- [x] *"The behavior described above is implemented on the listed files."* — The
  listed files set is empty; the behavior (a DB constraint) is not an API2
  behavior. Satisfied vacuously for this repo.
- [x] *"Existing behavior is unchanged when the new feature is not exercised."* —
  Trivially true; no code changed.
- [x] *"Unit and (where observable) e2e tests cover the new behavior."* — The new
  behavior is not observable from API2 (no affected endpoint on `master`), so no
  API2 test is applicable. Constraint-enforcement tests belong with the schema
  change in the Postgres repo.

## Open questions / action for the human reviewer

1. **The actual work belongs in the Postgres schema repo.** Add the composite
   `UNIQUE (ProjectShardId, Name)` constraint to the 5 tables there (Liquibase
   changeset under `PostgreSQLDatabase/Database/xyz/Constraints/`). This report
   does not and cannot do that from this repo.
2. **Pre-existing duplicates will block the constraint.** The spec puts
   dedup/backfill out of scope, but adding a UNIQUE constraint will fail if any
   project already has duplicate `Name`s in these tables. Confirm a dedup/backfill
   plan exists before the schema migration is applied.
3. **Future API2 follow-up (not required now):** once the create endpoints for
   these entities (currently on feature branches) merge to `master`, consider
   mapping the Postgres unique-violation error to a clean `409 Conflict` in
   those controllers. Out of scope for this spec; flagging for awareness.

## Commands run

- Build/tests were **not** run: there are no code changes to compile or test,
  and per task instructions the toolchain was not installed/searched for.