This is an internal working record, not an everyday instruction. It was written while the system was being rebuilt, for whoever maintains it. If you are here to do today's work, use the everyday documents instead: Procedures · Processes · Runbooks · The working day, step by step

Process Migration Readiness Extension¶

Status: CURRENT P6/P12 MIGRATION INPUT STANDARD
Owns: the additional information required to migrate an approved business process from current PHP Runtime to React + Next.js + TypeScript + worker without changing its meaning
Does not own: process semantics, Product scope, Task status, repository layout approval or migration execution
Context: Context Appendix M
Base process standard: PROCESS_CONTRACT_STANDARD.md
Portfolio: OPERATING_MODEL_PROCESS_PORTFOLIO_AND_MIGRATION_MAP.md
Target technology: Context Appendix L

1. Purpose¶

PROCESS_CONTRACT_STANDARD.md defines what a process means. This extension defines what must be known before that process can become a safe migration unit.

It is a companion standard, not a replacement and not a second process registry.

approved business meaning
+ current runtime characterization
+ target responsibility map
+ one-writer coexistence
+ parity / rollback / caller-zero
= migration-ready process packet

2. Readiness Levels¶

M0 — UNMAPPED¶

Required facts are absent or contradictory.

Typical conditions:

no stable process ID;
no accountable owner;
normal path is inferred from source;
completion or recovery is undefined;
target role and tenant applicability are unknown.

M0 processes are not migration candidates.

M1 — DOCUMENTED¶

Minimum process identity exists.

Required:

process ID and type;
purpose and business outcome;
profile applicability;
trigger, major actors and entry points;
major records and current owner;
normal path and known exceptions;
explicit unknowns.

M1 supports analysis, not implementation cutover.

M2 — SOURCE-RECONCILED¶

Current runtime behavior is sufficiently traced.

Required:

exact source revision;
current pages, APIs, helpers, jobs, providers and direct entry points;
source-of-truth tables/records and stable IDs;
mutation, transaction and effect boundaries;
compatibility mirrors/adapters;
static and dynamic callers where available;
current error, duplicate, timeout and partial-result behavior;
source/runtime discrepancies recorded.

M2 does not prove target-role operation.

M3 — OPERATIONALLY VERIFIED¶

Actual required roles verify the process.

Required:

normal path;
expected denial;
validation/error path;
duplicate/retry/unknown-result path;
correction/reopen/void/reversal path where applicable;
provider/device/physical recovery where applicable;
exact authoritative readback;
target tenant/profile coverage;
cleanup and observation evidence.

Administrator-only or source-string evidence does not qualify.

M4 — MIGRATION READY¶

Current and target responsibilities plus cutover are approved.

Required:

React UI responsibility;
Next.js Web/API adapter responsibility;
framework-independent TypeScript command/query/policy responsibility;
MySQL repository/transaction responsibility;
worker/outbox/retry responsibility;
one authoritative mutation owner during coexistence;
compatibility route and removal condition;
exact parity and reconciliation checks;
traffic/capability selection;
rollback without uncontrolled data repair;
caller-zero method;
Wiki/manual update and acceptance plan;
approved migration wave and owner.

M4 is required before P12 write cutover.

M5 — MIGRATED AND STABILIZED¶

Required:

target-role acceptance on the new runtime;
expected negative/retry/recovery behavior;
release/config/schema identity readback;
observation threshold passed;
legacy callers zero or explicitly retained;
replaced PHP page/API/helper/job removed or redirected;
documentation and Wiki current;
rollback or fail-forward posture approved;
value/stability outcome recorded.

3. Process Packet Header¶

Every migration packet begins with:

process_id:
contract_version:
process_lifecycle:
migration_readiness:
value_stream:
composite_parent:
tenant_profiles:
target_roles:
source_revision:
deployed_revision_if_verified:
process_owner:
migration_writer:
acceptance_owner:

Unknown values remain UNKNOWN.

4. Business Outcome And Scope¶

Record:

trigger;
business outcome;
normal completion evidence;
incomplete/partial dispositions;
cancellation/correction/reversal semantics;
explicit non-goals;
optional versus mandatory child processes;
Product/profile variation;
what a successful UI action does not prove.

The migration must not silently tighten or loosen business rules.

5. Actor, Role And Cadence¶

Record:

Field	Requirement
Accountable process owner	Role/team responsible for the result
Performing roles	Roles that execute each command
Reviewing/approving roles	Human decision owner where required
Backup/escalation	Owner when normal path cannot continue
Cadence	per request/job/shift/day/month/event
Service expectation	approved SLA or `UNKNOWN`
Menu/page visibility	expected access, distinct from API authorization
Tenant/profile policy	capability/configuration rule, never numeric ID behavior

6. State And Handoff¶

For every state or checkpoint:

state/checkpoint name
source record and fields
authoritative owner
entry condition
allowed commands
exit evidence
next process and carried IDs
retry/duplicate behavior
correction/reopen/void/reversal
manual recovery

For a composite, reference child states rather than inventing a duplicate composite state machine.

7. Current Runtime Characterization¶

7.1 Entry points¶

menu and page routes;
direct URLs;
public/webhook/provider entry points;
API methods/routes/actions;
CLI/cron/job/script entry points;
file/import/device inputs.

7.2 Current code responsibility¶

page/controller;
API route/transport;
application/helper/business logic;
SQL/query helper;
transaction owner;
shared/common dependencies;
provider/hardware/file adapters;
global/session/config dependencies.

7.3 Data and effects¶

authoritative records;
compatibility mirrors;
derived projections;
audit/ledger/evidence;
provider/physical effects;
exact readback;
backup/restore/import/export dependencies.

7.4 Current failure behavior¶

validation;
permission;
duplicate and concurrency;
timeout/unknown result;
partial commit;
provider failure;
retry;
compensation;
manual fallback.

8. Target React Responsibility¶

React owns only user-interface responsibility.

Packet requirements:

route/page component tree;
reusable components;
Client Component boundaries;
form and interaction state;
server-provided initial context;
validation presentation;
loading/empty/denied/error/success states;
duplicate-submit prevention presentation;
retry and recovery interaction;
focus, keyboard, accessibility, mobile and responsive behavior;
Tailwind tokens/patterns;
compatibility components for legacy embeds where needed.

React state is not source-of-truth completion.

9. Target Next.js Responsibility¶

Record:

App Router path and layouts;
Server Component data composition;
Route Handlers required by browser/external consumers;
UI-local Server Actions, if used;
session/auth/tenant context bridge;
request ID, release identity and observability;
cache/freshness policy;
file upload boundary;
reverse proxy and fallback route;
health/readiness;
error-envelope mapping.

Rules:

Server Components normally call application queries directly.
Route Handlers and Server Actions remain adapters.
Operational source-of-truth data is uncached unless invalidation ownership is explicit.
Business SQL and state transitions do not live in route/component files.

10. Target TypeScript Application And Domain Responsibility¶

Record:

command names and inputs;
query names and outputs;
runtime schemas;
actor/tenant/profile/capability policy;
business invariants;
state transition rules;
transaction owner;
repository interfaces;
idempotency key and unknown-result resolution;
stable errors and conflict behavior;
audit/domain/outbox events;
provider/file/device contracts;
compatibility adapter contracts.

This layer must not import React, next/*, browser globals or transport types.

11. Target MySQL Repository And Transaction¶

Record:

exact tables and explicit columns;
tenant scope;
stable identity;
transaction boundaries;
conditional/CAS behavior;
concurrency and duplicate prevention;
read-after-write result;
correction/reversal/audit semantics;
migration and schema prerequisites;
fixture and cleanup;
performance-critical query baseline.

Do not add speculative multi-database abstraction for P11 before a real consumer.

12. Worker And Durable Effects¶

When the process includes scheduled, long-running or retryable work, record:

outbox/event producer;
event identity and schema;
worker consumer;
claim/concurrency strategy;
retry/backoff/dead-letter;
provider idempotency;
reconciliation source;
pending/failed/completed user state;
manual recovery;
restart/deploy behavior;
monitoring and alert ownership.

An in-memory queue in the Next.js Web process is not durable completion.

Mark worker scope NOT_APPLICABLE only with a reason.

13. Coexistence And One-Writer Cutover¶

Choose and document one strategy per request class.

A. React/Next.js UI -> legacy PHP adapter
B. Legacy caller -> new TypeScript application adapter
C. Capability/traffic selector -> exactly one writer

Required:

authoritative writer before cutover;
authoritative writer after cutover;
selector and rollback;
read compatibility;
duplicate/double-submit behavior;
old/new result comparison;
schema/config version compatibility;
external effect ownership;
cutover observation;
prohibition on independent dual writes.

14. Caller-Zero And Retirement¶

Use both source and runtime evidence where applicable.

Inventory:

page/menu links;
JS/browser calls;
API clients;
direct URLs/bookmarks;
PHP includes/functions;
jobs/scripts/cron;
webhooks/providers;
reports/exports;
Wiki/manual links;
dynamic routing/loaders;
operational fallbacks.

Before deletion:

migrate or redirect every active caller;
preserve approved old URL behavior or deprecation;
verify runtime usage window;
update Wiki/manual/runbook;
exercise rollback or approve fail-forward;
confirm no required PHP/KJDatabase responsibility remains.

15. Acceptance Matrix¶

At minimum:

Scenario	Required proof
Normal	target-role outcome and exact readback
Empty/not applicable	clear non-error state
Validation	no mutation and actionable error
Denied role/module	no mutation or disclosure
Foreign tenant	rejected/no data
Duplicate/double click	one logical result
Timeout/unknown response	idempotent reread/retry
Concurrent conflict	explicit conflict; no silent overwrite
DB failure	rollback; no orphan effect
Provider/worker failure	visible recoverable state and reconciliation
Correction/reopen/void	approved provenance-preserving path
Legacy rollback	old path restored without uncontrolled repair
Mobile/accessibility	required UI path remains usable

16. Wiki And Manual Migration¶

Record:

affected slugs;
old and new entry points;
unchanged business meaning;
updated normal procedure;
exception/recovery changes;
screenshots and terminology;
publication authorization;
field review;
readback;
old-content retirement.

Internal migration implementation is not copied into user-facing Wiki content.

17. Readiness Review¶

The packet ends with:

current readiness: M0-M5
met criteria:
missing criteria:
blocking unknowns:
accepted risk:
selected next Task/wave:
user/process-owner decision:

No tool or generated score promotes readiness automatically.

18. Effect Boundary¶

This standard authorizes no Runtime, dependency, service, DB, provider, account, Wiki or deployment effect. Each process migration uses an activated P12 wave with its own effect authorization and rollback.

---¶

Source: docs/processes/PROCESS_MIGRATION_READINESS_EXTENSION.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.