Skip to content

requirements.md

Latest commit

 

History

History
80 lines (66 loc) · 4.33 KB

requirements.md

File metadata and controls

80 lines (66 loc) · 4.33 KB
Raw

Requirements: Authoring API

Role. The library a Plan imports — the surface through which intent is written as code. It is what makes a Step a named declaration, a dependency a variable, and a revision a function of its parent. It realizes the data model of 01-data-model as a thing an author writes, and its output is evaluated per decision 0014. Each requirement refines: a CMP-R*.

Assumptions

  • CMP.API-A01 The author is an agent or a person writing code. The surface is judged by whether such an author writes a correct Plan without consulting a grammar — the same standard the whole pivot to code was made against.

Requirements

  • CMP.API-R01 Identity is the declaration. A Step's identity is the binding it is declared under, so authoring an identity and authoring the work are the same act. The surface must offer no way to set an identity separately, because a separate identity is a value that can be set wrongly. refines: CMP-R10, CMP-R02.

  • CMP.API-R02 A dependency is a reference, not a name. A Step depends on another by referring to its binding, never by writing its identity as a string. An unresolved dependency must therefore be a reference that does not exist — caught where it is written — rather than a dangling edge discovered later. refines: CMP-R10.

  • CMP.API-R03 A revision is a function of its parent. Producing a version from a prior one is an operation on that version. It takes edits, additions, and retirements, and offers nothing that removes a Step: every Step of the parent is carried forward by the operation itself, so a Step cannot be dropped by omission. refines: CMP-R02.

  • CMP.API-R04 An edit names the Step it changes. Editing a carried-forward Step refers to that Step through the parent, so the edit cannot silently create a new Step or target one that is not there. What an edit may change is the work, the acceptance, and the dependencies; it cannot change identity. refines: CMP-R02, CMP-R10.

  • CMP.API-R05 A cross-plan reference is an import. Referring to another Plan's version is importing it. The import is what makes the reference checkable rather than spelled, and it is why the other Plan must be present to evaluate this one. The imported version is a reference, never a parent of the importing version. A Step depending on a Step in another Plan is a larger feature with unsettled cross-Plan readiness semantics and is deferred (DQ11); this requirement covers the reference, not the dependency edge. refines: CMP-R08, CMP-R09.

  • CMP.API-R06 The evidence vocabulary is open and typed. The constructors for acceptance evidence are values a use case defines, not a fixed set the API ships. Their shape is expressed in the type system, so a mistyped attribute or value is caught while authoring — but the API defines no vocabulary of its own and privileges none, keeping the model domain-neutral. refines: CMP-R08, CMP.DM-R13d.

  • CMP.API-R07 A plan is pure data. The surface exposes only construction of values. It offers nothing that reads the clock, the filesystem, the network, or the environment, and composing a Plan cannot have an effect. Purity is a property the API must not let an author violate through it, independent of the evaluation environment that also forbids it. refines: CMP-R12, CMP-R13.

  • CMP.API-R08 The output is authored, not generated. What the author writes is the stored version — the API does not compile intent into a separate form behind the author's back. A reader of a committed version reads the same library calls the author wrote. refines: CMP-R02.

  • CMP.API-R09 Starting is one import and one call. Authoring a first Plan requires importing the library and calling it — no configuration, no registration, no identifiers to obtain first. The floor of effort is a single file that already runs. refines: CMP-R11.

  • CMP.API-R10 The API is versioned, and a plan records what it was authored against. The library will change, and a committed version is immutable and read forever. A version must be evaluable under the API it was written against, so the API carries a compatibility identity and a version declares it. refines: CMP-R07.