Transactional Plan Materialization

The problem: promotion crosses a consistency boundary

Planning models tolerate revision. A team can add a task, change its parent, or alter a finish-to-start dependency as it learns. A work package has a different role: it is an authoritative instruction surface with acceptance criteria, closeout criteria, risk and control settings, governed context, requirements, dependencies, artifact references, and a scope binding. If a service copies whatever rows happen to be visible into that object, the result may represent no state that the operator selected. If the service commits the package but not its command record, a caller that times out cannot know whether a retry will duplicate work.

These concerns meet at materialization. The operation must decide which initiative revision is admissible, derive package and scope content from initiative state, and create the package together with the records that explain why it exists. This is a consistency boundary across domain models. It is narrower than a database-wide snapshot: the repository operation concerns one tenant-scoped initiative and its work-breakdown data, plus the package and event writes required by the transaction.

Mechanism: precondition, derive, commit, replay

Let I_r denote an initiative at revision r, with node set N and dependency-edge set E. A materialization command c carries tenant and initiative identifiers, command identity, an expected initiative revision r_e, package version and title, artifact inputs, baseline selection, and the archived-node policy. The service first validates command shape. Within the materialization transaction, it checks for an existing result under the command identity. If none exists, it loads the initiative for update against r_e and reads the initiative’s nodes and edges through the same transaction interface. A revision mismatch is a failed precondition: the service does not reinterpret the command against a newer initiative revision.

The planning basis is initiative-scoped. The transaction reads the initiative, WBS nodes, and dependency edges, then resolves package type and baseline references through transaction ports. It derives a supplied scope tree and dependency graph, creates package revision content, and computes the request and command-payload hashes used by the application contract. The resulting package revision carries a leaf-scope binding and references for the requirement set, dependency graph, governed context, baselines, external initiative binding, artifacts, and rendered context. The package domain computes its canonical review-subject hash by hashing a canonical representation of defined review fields. That digest identifies the review subject; it does not certify execution correctness or freeze unrelated database state.

The service records the command, opens and registers the package, registers synthesized artifact references when required, and inserts planning and materialization events through transaction interfaces. The transactor encloses these effects in one transaction callback. An error aborts the operation according to the storage adapter’s transaction behavior. The application contract therefore ties command identity, package creation, references, and event recording to one transaction boundary. It does not claim distributed atomicity with external systems or stronger isolation than the configured store provides.

On replay, the service looks up the materialization by command ID before deriving fresh content. It checks the payload hash and retrieves the recorded package revision content. It validates that content against the replay request, then re-establishes the command record and returns the event’s original package and scope-tree revision IDs with a replay marker. A different payload under the same command identity is an idempotency conflict. Missing or inconsistent recorded context is a materialization context conflict. This is application-level idempotency: a stable command names one intended effect, and the service returns its recorded result rather than creating a second package.

c(r_e, id, payload) → transaction: check replay; validate I_r = I_r_e; derive from (I, N, E); record command + package + events → result IDs

Worked trace: lost response and conflicting retry

An initiative at revision 12 contains a backup task and a schema-change task. A finish-to-start edge orders the schema change after the backup. The operator reviews that planning state and submits command id q with expected initiative revision 12. The transaction reads revision 12, its nodes and edges, derives the scope tree and dependency graph, opens package revision p, and records a materialization event linking q, p, and scope-tree revision s. The commit succeeds. The response is lost on the network.

The client retries q with the same payload. The service finds the event before attempting a fresh materialization, checks the payload hash, loads p’s recorded content, and returns p and s with Replayed=true. A new package is not opened. If the client reuses q with a changed title or another request field included in the payload hash, the replay conflicts. If a later edit has advanced the initiative to revision 13, a new command that still expects revision 12 fails its precondition. The caller must inspect the changed planning state and choose a new command. This trace covers one operation and its application-level transaction; it does not imply a serializable snapshot across all tenant data.

Evaluation method and limits

A useful implementation evaluation injects retries around the actual materialization boundary. It checks one fresh request, a same-command same-payload replay, conflicting command reuse, stale expected revision, and errors at package, artifact-reference, command-record, and event writes. The key outcomes are whether a successful retry returns the original revision IDs and whether failed transactions leave no partial materialization under the adapter’s transaction contract. Tests should also change dependency edges and archived-node selection to confirm that derived package content follows the selected initiative-scoped basis.

This paper reports no benchmark or production rate. Transaction isolation and rollback behavior depend on the repository implementation and storage adapter. The command contract does not make the chosen plan sound, resolve semantic conflicts in dependencies, or cause agents to obey package criteria. It provides a controlled and replayable transition from planning state to a canonical package revision. Operators still decide which plan to promote and which accepted references to bind.

Related work

Database transaction research studies atomic state changes and their isolation limits. HTTP semantics define idempotent methods by their intended effect, while application commands can also carry an explicit identity and payload comparison for operations exposed through non-idempotent transport methods. Provenance models describe entities, activities, and agents that produce records. Materialization uses a narrower operational form: package revisions, planning events, command identity, and initiative references connect the selected planning basis to the created work object.

Related sources: [1], [2], [3]