feat(project-engine-client): meter prompt units as texts × models in the mock (LLMO-5616)

[byteclimber]

What & why

The Project Engine mock metered prompts as a raw row count with no model factor, so the texts × models prompt-unit identity that the dynamic-allocation design rests on (serenity-docs#22 §2, live-verified 2026-07-02) was untestable. Per Rainer's follow-up on serenity-docs#22 (comment), teach the mock the multiplier so a regression in the net-delta sizing can be caught.

Changes (mock only; nothing published ships)

• mock/quota.js: promptsUsed is now Σ_project (texts × models) — derived live from the prompts:{ws}:{proj} and ai_models:{ws}:{proj} collection sizes, so a model add/remove (or prompt/project delete) re-meters automatically. Adds modelsUsed(ws, projectId) and canAddModel(ws, projectId); canCreatePrompts(ws, projectId, count) now sizes the batch by the project's model count. A model-less project consumes zero units.
• Routes: the v2 model-attach route 405s when attaching a model would re-meter existing texts past the allocation; both prompt-create routes (aio/prompts, aio/prompts/tagged) pass project_id so the batch is sized texts × models.
• Tests: quota.test.js (100% branches — the package gate) covers the multiplier, zero-models-free, and canAddModel; the e2e adds the texts × models prompt-create 405 and the model-attach 405 cases.

Pairs with

• Enables the swap (net delta 0 → zero transfers) / pure-removal (net delta < 0 → one release) integration tests on feat(serenity): dynamic AI resource allocation — consolidated allocator + kill-switch + hot-path wiring (LLMO-5616) spacecat-api-service#2764 (the net-delta sizing fix), which need this model-aware mock to exercise the multiplier.
• Sibling of the User-Manager mock work (feat(user-manager-client): per-workspace AI resource accounting + /resources reads (LLMO-5616) #1767, the parent-pool side) — this is the Project-Engine (metering) side; they are separate packages.

Gates

test:types clean, lint clean, unit tests 100% coverage (lines/branches/statements), e2e green (70 passing).

🤖 Generated with Claude Code

[github-actions]

This PR will trigger a minor release when merged.

[MysticatBot]

Hey @byteclimber,

Verdict: Request changes - two documentation files are now stale after this change.
Complexity: HIGH - medium diff; API surface signal.
Changes: Teaches the Project Engine mock to meter prompt units as texts x models, adding model-attach quota enforcement and updating unit/e2e tests (6 files).
Note: CI checks are currently pending - verify before merge.

Must fix before merge

1. [Important] Package CLAUDE.md is now stale - quota enforcement list incomplete - packages/spacecat-shared-project-engine-client/CLAUDE.md

   The CLAUDE.md states: "AI-unit quota (the disguised-405 the live API returns for an over-allocation) is in mock/quota.js, set via the POST /__quota control route or buildSeed({ quota }), enforced on project create / prompt write / publish."

   After this PR, quota is also enforced on model attach (POST /v2/.../ai_models returns 405 when re-metering existing texts would exceed the allocation). Update the enforcement list to include "model attach" so the doc remains accurate for the next reader.

2. [Important] docs/mock-usage.md is now stale - ai_models POST route description incomplete - packages/spacecat-shared-project-engine-client/docs/mock-usage.md

   The usage manual documents the AI models POST route as returning only 201. After this PR, the route also returns 405 when attaching a model would exceed the prompts allocation. Update the route documentation to note the metered behavior, consistent with how other metered routes (project create, prompt write, publish) are documented there.

Non-blocking (3): minor issues and suggestions

• nit: ai_models.js quota guard lacks the explanatory comment about 405 being undeclared in the OpenAPI spec - prompts.js has this comment and maintaining the pattern helps future readers - mock/counterfact/routes/v2/workspaces/{id}/projects/{project_id}/ai_models.js:33
• suggestion: E2E model-attach test could verify the model was NOT persisted after the 405 rejection (a follow-up GET asserting model count == 1 would catch persist-before-check regressions) - test/e2e/project-engine-mock.e2e.js:1749
• suggestion: Add a cross-project unit test for canAddModel that seeds two projects with usage and verifies that project A's consumption counts against project B's ability to add a model - test/mock/quota.test.js

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 1m 45s | Cost: $4.11 | Commit: b06adc0f0be5c660b4ed54592212e5d35e6e152d
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[MysticatBot]

Hey @byteclimber,

Verdict: Approve - all prior findings addressed; metering logic is correct.
Complexity: HIGH - medium diff; API surface signal.
Changes: Teaches the Project Engine mock to meter prompt units as texts x models, adding model-attach quota enforcement and corresponding unit/e2e tests (8 files).
Note: Recommend a human read before merge - this change modifies package-level documentation (CLAUDE.md) that anchors the mock's quota contract. The bot review is a complement to, not a replacement for, a human read here.
Note: CI checks are currently pending - verify before merge.

Non-blocking (2): minor issues and suggestions

• nit: canAddModel uses store.size(...) directly for the project's text count rather than routing through a named accessor like modelsUsed() does for models - minor abstraction inconsistency - mock/quota.js:170
• suggestion: Add a symmetric unit test for canAddModel on a project with zero texts (model attach is free when there are no texts to re-meter) - mirrors the existing "zero models = free" test - test/mock/quota.test.js

Previously flagged, now resolved

• CLAUDE.md updated with "model attach" in enforcement list and texts x models unit explanation
• mock-usage.md updated with metered 405 behavior and multiplier formula
• Explanatory 405 comment added to ai_models.js quota guard
• E2E test verifies rejected model NOT persisted (GET after 405 asserts count == 1)
• Cross-project unit test for canAddModel added (target-project isolation)

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 1m 25s | Cost: $4.10 | Commit: 306e43d1413d61ae2e98203d23204b84461c5fdc
If this code review was useful, please react with 👍. Otherwise, react with 👎.}