migrate-application-operation

# Create Or Migrate Application Operation

Create or migrate one bounded semantic operation at a time. Share authorization and business behavior without forcing internal APIs, public APIs, Copilot, and other tools to share authentication, input schemas, or response shapes.

## Enforce the application boundary

Apply this invariant:

> Every real operation on persisted or protected data enters through an authorized application use case.

This includes mutations, content and metadata reads, canonical resource lookup, and reference-to-resource resolution when the lookup is authorization-sensitive.

Surface helpers may:

- Normalize an already-authenticated surface context into a `Principal`.
- Translate aliases or wire arguments into application input.
- Select a code-defined operation and application use case.
- Call the application use case.
- Translate typed results and errors into the surface contract.

Surface helpers must not:

- Query databases or storage.
- Decide workspace or resource authorization.
- Implement business transactions.
- Record semantic audit or shared domain notifications.
- Infer authoritative identity, workspace, audience, or scope from untrusted arguments.
- Substitute billing attribution for identity.

A helper that resolves a path is valid only when the actual protected lookup runs through an authorized application resolver. If a helper begins doing real data work, move that work into an application use case.

## Read the foundation first

Read these files completely before editing:

- `packages/auth/src/principal.ts`
- `apps/sim/lib/core/application/operation.ts`
- `apps/sim/lib/core/application/workspace-operation.ts`
- `apps/sim/lib/core/application/workspace-authorization.ts`
- `apps/sim/lib/core/application/authorized-workspace-use-case.ts`
- `apps/sim/lib/api/server/routes/definition.ts`
- `apps/sim/lib/api/server/routes/internal-json-route.ts`
- `apps/sim/lib/api/server/routes/v2-json-route.ts`
- `apps/sim/lib/auth/internal-delegation.ts`
- `apps/sim/lib/copilot/application/application-adapter.ts`
- `apps/sim/lib/copilot/auth/application-delegation.ts`

Use the file domain only as a representative golden slice:

- `apps/sim/lib/workspace-files/application/operations.ts`
- `apps/sim/lib/workspace-files/application/authorized-workspace-file-use-case.ts`
- `apps/sim/lib/workspace-files/application/rename-workspace-file.ts`
- `apps/sim/lib/copilot/application/execute-file-use-case.ts`
- `apps/sim/lib/copilot/auth/file-delegation.ts`

Then read the target domain's operation registry, application code, repositories, contracts, adapters, aliases, resume paths, and focused tests. Fail immediately if the shared foundation is absent. Do not recreate it inside the domain.

## Bound the migration

Inventory every entry point for the behavior before editing:

- Internal HTTP routes and contracts.
- Public or versioned API routes and contracts.
- Copilot tools, aliases, resume paths, and polymorphic branches.
- Other tool servers, workflow executors, jobs, or service callers.
- Current authentication, authorization, workspace assertions, and concealment.
- Manager or orchestration call chains.
- Audit, notification, analytics, and billing side effects.
- Error/status/result behavior.
- Rate-limit identity, rollout gates, quota, and concurrency admission.

Classify each as `migrate`, `defer`, or `non-goal`. Do not migrate adjacent operations merely because they share a module. Do not modify v1 unless the request explicitly includes it.

Preserve behavior unless the task explicitly changes it. Stop and report a decision when surfaces currently disagree on security or compatibility behavior; do not silently choose one.

## Freeze observable behavior before editing

Treat the legacy route or tool as an ordered program, not merely a bag of business logic. Before moving code, write a compact baseline for every in-scope entry point and add focused characterization tests for behavior not already pinned down.

Capture all of these when they apply:

- Accepted inputs, including trimming, blank omission, duplicate query keys, aliases, defaults, and bounds.
- Authentication and authorization order, minimum roles, resource membership, concealment, and exact error/status mapping.
- Exact success bodies, optional fields, status codes, redirects, cookies, headers, and binary or stream behavior.
- Mutation ordering, transaction boundaries, idempotency, no-ops, and observable state after each possible partial failure.
- Audit, notification, analytics, and billing timing plus exact semantic dimensions and attribution.
- Browser or protocol state ownership, concurrency isolation, expiry, callback ordering, and cleanup behavior.
- Every value newly crossing into HTML, JavaScript, SQL, URLs, logs, provider payloads, or another encoding context.

Compare the old statement order with the proposed application lifecycle explicitly:

```text
legacy parse/normalize
  -> legacy authorization checks
  -> branch-specific canonical lookup
  -> mutation(s)
  -> per-step side effects
  -> response or redirect catch
```

Moving those steps under a wrapper may change behavior even when each individual call is reused. In particular:

- `projectAudit` and `afterSuccess` run only after `execute` returns. They cannot describe earlier committed mutations when a later step throws. Make the compound mutation atomic or define explicit partial-result/failure projection semantics before migrating it.
- Operation metadata is executable policy. Adding a resource role to a workspace-only legacy read is an authorization change, not an architectural cleanup.
- A shared error policy does not automatically preserve route-local concealment, subclass ordering, browser redirects, or branch-specific messages.
- A shared contract does not automatically preserve manual `URLSearchParams` normalization or exact legacy response unions.
- A shared use case may own domain behavior while separate surface presenters still preserve