cs-image-system-contract 0.1.4__tar.gz

cs_image_system_contract-0.1.4/.gitignore

@@ -0,0 +1,26 @@
+.envrc
+# Okta API-integration key material -- never commit
+.private_key.pem
+.private_key.json
+.public_key.json
+*.pem
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+.DS_Store
+packages/**/*.code-workspace
+trial
+tfmodules/tftest
+YAML_DUMP.yaml
+.obsidian
+.tofu-plugin-cache/
+_uncommitted/
+target/
+# never publishable, whatever the root (stage 35 refuses them; stage 40's publish-tree checks the policy)
+tfplan
+*.tfstate
+*.tfstate.backup

cs_image_system_contract-0.1.4/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cs_image_system_contract-0.1.4/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.5
+Name: cs-image-system-contract
+Version: 0.1.4
+Summary: The plugin contract of cs-image-system: the protocols, constants and data carriers a plugin is written against, with no dependency on the core
+Project-URL: Repository, https://github.com/infrastructurebuilder/cs-image-system-3
+Project-URL: Documentation, https://github.com/infrastructurebuilder/cs-image-system-3/blob/develop/docs/OPERATIONS.md
+Project-URL: Package README, https://github.com/infrastructurebuilder/cs-image-system-3/blob/develop/packages/contract/README.md
+Author-email: Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: packaging>=26.2
+Requires-Dist: pydantic>=2.13
+Description-Content-Type: text/markdown
+
+# cs-image-system-contract
+
+The plugin contract: the one package a plugin is written against. It
+carries the protocols a model and a builder satisfy, the constants and
+field helpers a model is declared with, the lifecycle phases a hook keys
+on, and the data carriers a hook returns. It depends on no other package of
+the system -- `pydantic` and `packaging` only -- and the core
+([base](../base/README.md)) depends on it, never the reverse: the contract
+is upstream, the core conforms to it, and a new hook is a contract change
+first. The core's base classes are the convenient implementation of the
+contract, not the contract itself; a class that satisfies the protocols
+structurally is a first-class plugin, and
+[`testing.assert_conforms`](src/cs_image_system/contract/testing.py) is the
+check that says so. Stage 30 made the package (2026-10-29); until then the
+protocols lived inside `base`, imported the registry, and a plugin's
+`pyproject.toml` depended on the CLI host.
+
+One module per kind of builder, over a shared core:
+
+| Module | Carries |
+| --- | --- |
+| [`core`](src/cs_image_system/contract/core.py) | `PluginArtifactProtocol` (`csis_name`, `csis_classifier`), `NameTypedProtocol`, `PluginMetadataProtocol`, `BuilderModelProtocol` and `RuntimeEnabledBuilderModelProtocol` (what the core reads of any builder model), `BuilderProtocol` (the six universal hooks, the three finalize-phase hooks, `finalize`, the paths), and the three markers the orchestrator dispatches on: `SelfInjectedNameProtocol`, `SubItemOverrideProtocol`, `ParentPropertyHoldingProtocol`. |
+| [`runtime`](src/cs_image_system/contract/runtime.py), [`operating_system`](src/cs_image_system/contract/operating_system.py), [`storage`](src/cs_image_system/contract/storage.py), [`image`](src/cs_image_system/contract/image.py), [`instance`](src/cs_image_system/contract/instance.py), [`modification`](src/cs_image_system/contract/modification.py), [`group`](src/cs_image_system/contract/group.py), [`user`](src/cs_image_system/contract/user.py), [`state`](src/cs_image_system/contract/state.py) | One `<Kind>BuilderModelProtocol` and one `<Kind>BuilderProtocol` per kind, with exactly the attributes and hooks the core reads. `state` also carries the backend seam: `StateLocation`, `BackendRegistration`, `BackendKindProtocol` and `StateBackendModelProtocol`. `image` carries the provider-specific image's two enums. |
+| [`metadata`](src/cs_image_system/contract/metadata.py) | `PluginMetadata`, the record a plugin's entry point returns. |
+| [`constants`](src/cs_image_system/contract/constants.py) | `VCT` (the classifications), the sentinels (`DEFAULT`, `SELF`, `NONE`, `OOPS_DEFAULTS`), the field metadata keys, `PLUGIN_TYPES` (the entry-point groups), the collection names, the file names a run writes. |
+| [`model_config`](src/cs_image_system/contract/model_config.py) | `CSIS_MODEL_CONFIG`, the one pydantic configuration every model is declared under (unknown keys are refused). |
+| [`fields`](src/cs_image_system/contract/fields.py), [`field_kinds`](src/cs_image_system/contract/field_kinds.py) | `fk_field`, `templated_field`, `deferred_list_field`, `deferred_list_fk_field`, `parent_field`; the open registry of field kinds a plugin may extend. |
+| [`lifecycle`](src/cs_image_system/contract/lifecycle.py), [`lifecycles`](src/cs_image_system/contract/lifecycles.py) | `ExecutionLifecyclePhase`; `Lifecycle`, `LifecycleSpec` and the phases and builder classifications each built-in lifecycle owns. |
+| [`assets`](src/cs_image_system/contract/assets.py), [`executables`](src/cs_image_system/contract/executables.py) | `Asset`, `AssetSet` (what `generate_items_*` returns); `ExecutableProtocol`, `CFExecutables` (what `get_commands_to_run_*` returns). |
+| [`names`](src/cs_image_system/contract/names.py), [`hcl`](src/cs_image_system/contract/hcl.py) | `safe_name`, `super_safe_name`; `HclRaw`, `hcl_expr`, `render_module_call`. |
+| [`testing`](src/cs_image_system/contract/testing.py) | `assert_conforms(cls, protocol)` and `conformance_problems`. |
+
+### What moved where
+
+Stage 30 moved these from the core into the package. Every old path but
+`cs_image_system.base.protocols` still resolves: the module that held a
+name re-exports it from here (the shims), kept on purpose while the
+package is provisional. Removing the shims is the commitment to the
+contract, and is done together with moving the package to a repository
+of its own; until then an undo of the stage is a swap of which side
+holds the bodies, with no import rewritten anywhere.
+
+| Was | Is now |
+| --- | --- |
+| `base.constants` (all of it: `VCT`, the sentinels, the field metadata keys, `PLUGIN_TYPES`, the collection and file names) | `contract.constants` |
+| `base.models.model_config.CSIS_MODEL_CONFIG` | `contract.model_config` |
+| `base.helpers.field_helpers` (`fk_field`, `templated_field`, `deferred_list_field`, `deferred_list_fk_field`, `lookup_dataclass_field`) | `contract.fields`, plus the new `parent_field` |
+| `base.helpers.field_kinds` (the field-kind registry) | `contract.field_kinds` |
+| `base.lifecycle.ExecutionLifecyclePhase` | `contract.lifecycle` |
+| `base.lifecycles`: `Lifecycle`, `LifecycleSpec`, `LifecycleLike`, `LIFECYCLE_ORDER`, `LIFECYCLE_PHASES`, `LIFECYCLE_BUILDER_VCTS` (the registry functions stay in `base`) | `contract.lifecycles` |
+| `base.basic.asset`: `Asset`, `AssetSet` (`sort_and_write` now takes the generation path) | `contract.assets` |
+| `base.models.executable_adds.CFExecutables` (now generic over `ExecutableProtocol`) | `contract.executables` |
+| `base.protocols.plugin_metadata`: `PluginArtifactProtocol`, `PluginMetadataProtocol`; `base.protocols.name_typed_protocol`: `NameTypedProtocol`, `SelfInjectedNameProtocol`, `SubItemOverrideProtocol`; `base.protocols.builder_model_protocol`: `BuilderModelProtocol`; `base.protocols.parent_property_holding_protocol`: `ParentPropertyHoldingProtocol` (deleted, no shim; their default bodies are `base.models.mixins` and the base classes) | `contract.core` |
+| `base.protocols.state_management.StateManagementRootProtocol` (zero implementers) | deleted |
+| `base.utils.safe_name`, `super_safe_name` | `contract.names` |
+| `base.utils.HclRaw`, `hcl_expr`, `render_module_call` | `contract.hcl` |
+| `base.models.provider_specific_image.PSIState`, `PSISourceKind`, `psi_key` | `contract.image` |
+| `hashicorp_utils.collector.StateLocation`, `BackendRegistration`, the `BackendKind` protocol (still importable from the collector) | `contract.state` (`BackendKindProtocol`; `BackendWithoutKind` is new) |
+| nothing: new | `contract.metadata.PluginMetadata`, the kind protocols, `contract.testing` |
+
+The protocols carry no implementation. Where a default body existed
+(`global_id`, `get_classification`, `get_self_injected_name`, the parent
+reference's registry lookup) it lives in the core's base classes and
+mixins. The kind modules import `core` and only the kinds they declare they
+read (`runtime` reads `image` for the provider-specific image's enums);
+[tests/test_v2_contract.py](../../tests/test_v2_contract.py) holds that
+direction, holds the package to importing nothing from the core, and runs
+`assert_conforms` over every base class and every built-in plugin's models
+and builders.
+
+## Writing a plugin
+
+A plugin is a Python distribution with an entry point in the group
+`cs_image_system.plugins.<kind>` (`PLUGIN_TYPES` in `constants`: `runtime`,
+`state`, `modification`, `storage`, `group`, `user`, `image`, `os`,
+`instance`, `other`). The entry point loads to a zero-argument callable
+that returns one `PluginMetadata` or a list of them.
+
+1. **Depend on the contract.** In `pyproject.toml`, `dependencies =
+   ["cs-image-system-contract>=X"]`, with `X` the first release that
+   carries the contract (0.1.3 and before do not): a floor, not a pin --
+   the workspace's own packages pin each other at `==` because they
+   release together, an external plugin does not. Add `cs-image-system-base` only
+   if the plugin subclasses the core's base classes (every built-in plugin
+   does; it is the convenient way, not the required one). Never depend on
+   `cs-image-system-system`, the CLI host.
+2. **Write the model**: a pydantic dataclass, `@dataclass(kw_only=True,
+   config=CSIS_MODEL_CONFIG)`, that satisfies the kind's
+   `<Kind>BuilderModelProtocol`. The universal fields are `name`, `type`
+   (the field is `type_`, aliased `type`), `description`, `aliases`,
+   `executable`, `is_default`, `config`, `gitignore`, `tags`, with the
+   `get_*` readers and `finalize`; the kind's module says what more the
+   core reads. The class methods `csis_name()` (the value a YAML `type:`
+   names) and `csis_classifier()` (`VCT.<KIND>_BUILDER_MODEL`) are how the
+   registry resolves a `type:` to the class. A foreign key to another
+   builder is `fk_field(target=VCT....)`; a value the resolver renders is
+   `templated_field(...)`; an item that belongs to a builder declares
+   `_model_id = parent_field(VCT....)`.
+3. **Write the builder**: a class that satisfies the kind's
+   `<Kind>BuilderProtocol`: the universal surface in `BuilderProtocol`
+   (`generate_items_{before,during,after}` return an `AssetSet`,
+   `get_commands_to_run_{before,during,after}` a `CFExecutables`,
+   `pre_finalize_phase`/`post_finalize_phase`/`post_failed_phase` fire
+   around a phase's deferred commands, `finalize` once the configuration
+   is complete) plus the kind's domain hooks, and the same two class
+   methods, `csis_classifier()` returning `VCT.<KIND>_BUILDER`. The core's
+   `BuilderBase` and `<Kind>BuilderBase` implement every hook with a
+   default; subclass them to override only what the plugin does.
+4. **Return the metadata**: `PluginMetadata(services={KEY: [Model,
+   Builder]}, builders_for_models={Model: Builder})`, where `KEY` is the
+   `csis_name`. Item models a plugin injects under a classification go in
+   `injected_models`.
+5. **Prove it.** In the plugin's tests, `assert_conforms(Model,
+   <Kind>BuilderModelProtocol)` and `assert_conforms(Builder,
+   <Kind>BuilderProtocol)`; then a dry `cs-image-system run --all` over a
+   tree that declares the plugin's `type:`.
+
+A state backend is the smallest kind: a model that answers
+`to_backend_registration()` with a `BackendRegistration` naming its type's
+`BackendKindProtocol` (where a workspace's state lives, the settings the
+workspace's backend file carries, the settings a consumer's remote-state
+data source carries), and a builder that emits nothing; the core hands
+the registration to the terraform collector once the state backends are
+loaded. The [contract example plugin](../contract-example-plugin/README.md)
+is exactly that, written against this package alone with nothing of the
+core, and the proof the bar runs; the
+[local state plugin](../local-state-plugin/README.md) is the same kind
+written the convenient way on the base classes; the
+[dummy plugin](../dummy-plugin/README.md) is the template for a group or
+user builder and for a hook plugin.
+
+Not in the contract yet, so a plugin that needs them depends on `base`:
+the run context (`GlobalTypeContext`, reached today through a base
+builder's `_get_context()`; its protocol is a later stage), the
+`cs_image_system.plugins.hooks` entry point (`HookSet`, typed on the
+context) and the `cs_image_system.bootstrap` entry point (the bootstrap's
+sections).
+
+## Prerequisites and integration
+
+Nothing outside Python: the package needs Python 3.13 or later, `pydantic`
+and `packaging`, and no account, tool, credential or network. A plugin
+finds it by import (`cs_image_system.contract.<module>`); the core finds
+it the same way and pins it at its own version.
+
+## Configuration reference
+
+The contract reads no YAML of its own. What it declares about every
+builder's entry, read by the core through `BuilderModelProtocol`:
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `name` | str | required | The builder's name; `safe_name` normalises it, `display_name` keeps what was written. Not a word in `OOPS_DEFAULTS`. |
+| `type` | str | required | The plugin's `csis_name`, which the registry resolves to the model class; an alias resolves to the canonical name. |
+| `description` | str or null | null | Free text. |
+| `aliases` | set of str | empty | Other names the builder answers to. |
+| `executable` | str or null | null | The `executables:` entry the builder runs, version-checked at validation; null for none. |
+| `is_default` | bool | false | The default builder of its classification; one per classification. |
+| `config` | mapping | empty | The plugin's own settings. |
+| `gitignore` | list of str | empty | Entries the builder adds to the emitted `.gitignore`. |
+| `tags` | mapping of str | empty | Tags every resource the builder emits carries. |
+
+The kind modules say what more each kind reads (a runtime's defaults and
+credentials, an OS builder's family and query, a user builder's email
+templates); the plugin's own README is the reference for the fields it
+adds. Unknown keys are refused by `CSIS_MODEL_CONFIG` (`extra="forbid"`).
+The sentinels `default`, `self`, `none`, the empty string and null
+(`OOPS_DEFAULTS`) mean "not set" wherever a value is read, so nothing may
+be named after one of them. Variations: none; the contract behaves the same
+under a dry run and a real one, on every runtime.
+
+## What it tests and verifies
+
+- `assert_conforms(cls, protocol)` (`testing`): every member the protocol
+  declares exists on the class, every method takes the protocol's
+  parameters by name and kind in order (an implementation may add
+  parameters with defaults, or take `*args` and `**kwargs`), a property is
+  a property or a dataclass field, a class method a class method.
+  Annotations are not compared here; pyright does that where a class
+  lists its protocol as a base (its override check,
+  `reportIncompatibleMethodOverride`, is on as an error since hygiene XIX),
+  and a protocol a class lists as a base is the question, not an answer,
+  so its stubs never count. The core's
+  [tests/test_v2_contract.py](../../tests/test_v2_contract.py) runs it
+  over every base class and every built-in plugin's models and builders at
+  `just test`; a plugin's own tests should run it over theirs. The verdict
+  is an `AssertionError` naming every shortfall.
+- The import direction, in the same test: the package's sources import
+  nothing from `cs_image_system.base`, `.system` or `.hashicorp_utils`,
+  and each kind module imports only `core` and the kinds it declares.
+  [tests/test_v2_package_metadata.py](../../tests/test_v2_package_metadata.py)
+  holds the same line from the manifest: the package declares exactly the
+  third-party distributions it imports and reaches no sibling.
+- At load, the loader checks what an entry point returned with
+  `isinstance(..., PluginMetadataProtocol)` and logs an error for anything
+  else; the registry refuses a `csis_name` registered twice under one
+  classification (`Type Collision`).
+
+## When it fails
+
+- `AssertionError: <class> does not conform to <protocol>: <member>: ...`
+  from `assert_conforms`: the class lacks a member or a method's
+  parameters differ from the protocol's. Add the member or match the
+  signature; the protocol is the specification. If the shortfall is in a
+  core base class, the contract changed and the core did not follow: that
+  is the test doing its job, and the fix is in `base`.
+- `Plugin <name> did not return a valid PluginMetadataProtocol instance`
+  in the log at load, and the plugin's types unknown to every `type:`: the
+  entry point returned something other than a `PluginMetadata` (or a list
+  of them) -- a class instead of an instance, a dict, nothing.
+- `Type Collision: <name>` at load: two plugins register one `csis_name`
+  under one classification; rename one.
+- `BackendWithoutKind` (`state`): a `BackendRegistration` was built without
+  its `kind`; the model's `to_backend_registration()` must name the type's
+  `BackendKindProtocol` object.
+- `<Model> ... Extra inputs are not permitted` at load: a YAML key the
+  model does not declare (`CSIS_MODEL_CONFIG` refuses unknown keys); the
+  plugin's README names the fields it reads.
+- `ModuleNotFoundError: No module named 'cs_image_system.base.protocols'`
+  from a plugin written before stage 30 running on this tree: the
+  protocols moved here, with no shim; import them from
+  `cs_image_system.contract.core`.
+
+No failure of this package has happened in the field yet (2026-10-29).
+
+## Related
+
+- [docs/PLUGINS.md](../../docs/PLUGINS.md), the index of every package.
+- [base](../base/README.md), the core that implements the contract.