Clarify printing queues and add duration timers #617

Activity

1. Adr1an04

   self-assigned this

   on Oct 10, 2026
2. Adr1an04

   added

   BugSomething isn't workingSomething isn't working

   MinorSmall change - 1 reviewer requiredSmall change - 1 reviewer required

   APIChange modifies code in the global API/tRPC packageChange modifies code in the global API/tRPC package

   on Oct 10, 2026
3. coderabbitai commented on Oct 10, 2026

   

   coderabbitaiBot

   on Oct 10, 2026 – with coderabbitai

   More actions

   Coding Plan

   Summary

   • The runtime endpoint already exists. The CI failures come only from missing contract metadata.
   • Add the client path to the sorted API surface snapshot.
   • Declare the endpoint as hybrid, following the printing.updateStatus precedent. Only actual category changes are audited.
   • Validate with the two contract suites and root format, lint, and typecheck.

   Design Choices

   Design Choice 1: Scope of integration tests for the admin `updateCategory` branches

   Options Considered:

   1. Change only the snapshot and the coverage declaration.
   2. Also add database-gated integration tests in tests/integration/printing.test.ts.

   Chosen Option: 1

   Rationale: The ticket scope and AGENTS.md require the smallest correct change. Missing branch tests are a separate issue.

   💡 User Tips

   Regenerate the plan with different choices with @coderabbitai <feedback>.

   Implementation Steps

   Phase 1: Register the Endpoint in Contract Metadata

   Add printing.updateCategory to the two contract checks that fail in CI. Do not change runtime code.

   The current tests do not cover the audited-change branch or the no-op branch for the admin endpoint. The ticket asks only for contract-check registration.

   Task 1: Add the Endpoint to the API Surface Snapshot

   Make the snapshot match the procedure paths that are already registered.

   • Create a task branch before editing, as AGENTS.md requires.
   • Update packages/api/src/tests/root/__snapshots__/api-surface.test.ts.snap. Insert "printing.updateCategory", between "printing.setEstimatedReadyAt", and "printing.updateStatus",.
   • Preferred method: run pnpm --filter=@forge/api test src/tests/root/api-surface.test.ts --update from the repository root.
   • Confirm that the snapshot diff contains only this one added line.
   • Do not modify root.ts or routers/printing.ts.

   Task 2: Declare Hybrid Audit Coverage

   Classify the endpoint as conditionally audited.

   • Update packages/api/src/utils/audit/coverage.ts. Add "printing.updateCategory" to HYBRID_ADMIN_PROCEDURES next to printing.updateStatus.
   • Add a short comment in the existing style. A changed category writes printing.job.category_updated. Saving the same category is a no-op with no audit event.
   • Confirm that the entry is absent from the audited and excluded arrays. The disjointness test requires this.

   🤖 Prompt for AI agents

   Register `printing.updateCategory` in the API surface snapshot and hybrid audit
   coverage. Limit changes to the two metadata files.
   
   - Create a task branch before editing, as `AGENTS.md` requires.
   - From the repository root, preferably run `pnpm --filter=@forge/api test
   src/tests/root/api-surface.test.ts --update`.
   - In `packages/api/src/tests/root/__snapshots__/api-surface.test.ts.snap`,
   insert `"printing.updateCategory",` between `"printing.setEstimatedReadyAt",`
   and `"printing.updateStatus",`.
   - Confirm that the snapshot diff contains only the added line.
   - In `packages/api/src/utils/audit/coverage.ts`, add `"printing.updateCategory"`
   to `HYBRID_ADMIN_PROCEDURES` next to `printing.updateStatus`.
   - Add a short comment in the existing style. State that a changed category
   writes `printing.job.category_updated` and that saving the same category is a
   no-op with no audit event.
   - Keep the entry out of the audited and excluded arrays to satisfy the
   disjointness test.
   - Do not add integration tests or change runtime behavior or permission checks.
   - Do not modify `root.ts`, `routers/printing.ts`, `requirePrintingQueue`, the
   status precondition, the transaction, the audit event, or notification logic.
   

   Phase 2: Validate

   Run the contract suites and the mandatory root checks. Report the results accurately.

   Task 1: Run the Contract Suites

   • From the repository root, run pnpm --filter=@forge/api test src/tests/root/api-surface.test.ts src/tests/audit/coverage.test.ts.
   • If a test fails, fix only the metadata entry. Do not change router code.

   Task 2: Run the Root Checks and Review the Diff

   • From the repository root, run pnpm format, pnpm lint, and pnpm typecheck.
   • pnpm format only checks formatting.
   • If pnpm format reports a problem in a touched file, run Prettier write on that file only.
   • Run git diff --name-only.
   • Confirm that only the two metadata files changed.

   🤖 Prompt for AI agents

   Validate the contract metadata changes with the contract suites and mandatory
   root checks. Confirm that only the two metadata files changed.
   
   - From the repository root, run `pnpm --filter=@forge/api test
   src/tests/root/api-surface.test.ts src/tests/audit/coverage.test.ts`.
   - If a test fails, fix only the metadata entry. Do not change router code.
   - From the repository root, run `pnpm format`, `pnpm lint`, and `pnpm
   typecheck`.
   - Treat `pnpm format` as a formatting check. If it reports a problem in a
   touched file, run Prettier write on that file only.
   - Run `git diff --name-only`. Confirm that only
   `packages/api/src/tests/root/__snapshots__/api-surface.test.ts.snap` and
   `packages/api/src/utils/audit/coverage.ts` changed.
   - Report every command that was run and its actual result.
   - If the environment cannot run a check, state that the check was not run.
   

   Research

   Ticket Summary

   CI run 38060417381 fails because printing.updateCategory is missing from the API surface snapshot and the audit coverage declaration. Add the endpoint to the snapshot. Classify the endpoint as hybrid in audit coverage. Do not change runtime behavior or permission checks.

   Codebase Summary

   • printing.updateCategory is defined in packages/api/src/routers/printing.ts at lines 364–412.
   • packages/api/src/root.ts already registers the endpoint under printing.
   • The procedure requires PRINTING_QUEUE or IS_OFFICER.
   • The procedure accepts only jobs with the received or needs_clarification status.
   • If the category is identical, the procedure returns changed: false and writes no audit event.
   • If the category changes, the procedure writes printing.job.category_updated in the same transaction.
   • api-surface.test.ts snapshots the sorted keys of appRouter._def.procedures.
   • coverage.test.ts requires each permProcedure to have exactly one policy in utils/audit/coverage.ts.
   • The test checks only audited entries for an audit writer.
   • printing.updateStatus is the hybrid precedent at lines 186–187.
   • AGENTS.md requires a task branch, the smallest correct change, and root pnpm format, pnpm lint, and pnpm typecheck.

   File-Level Changes and Follow-Up Instructions

   File	Change
   packages/api/src/tests/root/__snapshots__/api-surface.test.ts.snap	Add "printing.updateCategory" in sorted position.
   packages/api/src/utils/audit/coverage.ts	Add "printing.updateCategory" to HYBRID_ADMIN_PROCEDURES with a no-op comment.

   • Edit only the two files listed above.
   • Do not change requirePrintingQueue, the status precondition, the transaction, the audit event, or notification logic.
   • Report every command that was run and its actual result.
   • If the environment cannot run a check, state that the check was not run.

   ---

   🚀 Next Steps

   🤖 All AI agent prompts combined

   Task: 1
   
   Register `printing.updateCategory` in the API surface snapshot and hybrid audit
   coverage. Limit changes to the two metadata files.
   
   - Create a task branch before editing, as `AGENTS.md` requires.
   - From the repository root, preferably run `pnpm --filter=@forge/api test
   src/tests/root/api-surface.test.ts --update`.
   - In `packages/api/src/tests/root/__snapshots__/api-surface.test.ts.snap`,
   insert `"printing.updateCategory",` between `"printing.setEstimatedReadyAt",`
   and `"printing.updateStatus",`.
   - Confirm that the snapshot diff contains only the added line.
   - In `packages/api/src/utils/audit/coverage.ts`, add `"printing.updateCategory"`
   to `HYBRID_ADMIN_PROCEDURES` next to `printing.updateStatus`.
   - Add a short comment in the existing style. State that a changed category
   writes `printing.job.category_updated` and that saving the same category is a
   no-op with no audit event.
   - Keep the entry out of the audited and excluded arrays to satisfy the
   disjointness test.
   - Do not add integration tests or change runtime behavior or permission checks.
   - Do not modify `root.ts`, `routers/printing.ts`, `requirePrintingQueue`, the
   status precondition, the transaction, the audit event, or notification logic.
   ===============================================================================
   
   Task: 2
   
   Validate the contract metadata changes with the contract suites and mandatory
   root checks. Confirm that only the two metadata files changed.
   
   - From the repository root, run `pnpm --filter=@forge/api test
   src/tests/root/api-surface.test.ts src/tests/audit/coverage.test.ts`.
   - If a test fails, fix only the metadata entry. Do not change router code.
   - From the repository root, run `pnpm format`, `pnpm lint`, and `pnpm
   typecheck`.
   - Treat `pnpm format` as a formatting check. If it reports a problem in a
   touched file, run Prettier write on that file only.
   - Run `git diff --name-only`. Confirm that only
   `packages/api/src/tests/root/__snapshots__/api-surface.test.ts.snap` and
   `packages/api/src/utils/audit/coverage.ts` changed.
   - Report every command that was run and its actual result.
   - If the environment cannot run a check, state that the check was not run.
   

   💡 Iterate on the plan with: @coderabbitai <feedback>

   Example Feedback
   - @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
   - @coderabbitai For design choice 1 go ahead with option 3 and replan.
   

   ---

   Start Coding →
4. Adr1an04

   removed

   MinorSmall change - 1 reviewer requiredSmall change - 1 reviewer required

   on Oct 10, 2026
5. Adr1an04

   changed the title [-]Register printing category endpoint in API contract checks[/-] [+]Clarify printing queues and add duration timers[/+] on Oct 10, 2026
6. Adr1an04

   added

   BladeChange modifies code in Blade appChange modifies code in Blade app

   Hack SitesChange modifies code in a Hackathon app (ex. 2025)Change modifies code in a Hackathon app (ex. 2025)

   UIChanges modifies code in the global UI packageChanges modifies code in the global UI package

   FeatureNew Feature or RequestNew Feature or Request

   MajorBig change - 2+ reviewers requiredBig change - 2+ reviewers required

   on Oct 10, 2026
7. Adr1an04

   added a commit that references this issue on Oct 10, 2026

   [#617] Clarify printing queues and add duration timers (#618)

   ...

   d8fa137
8. Adr1an04

   closed this as completedin #618on Oct 10, 2026