feat(kits): publish reusable kits for proven environment infrastructure

[Brad-Edwards]

Outcome

Authors can assemble realistic emulated environments from reusable, proven infrastructure building blocks instead of repeatedly recreating identity, endpoint, network, application, data, AI, and operational foundations by hand.

A kit is an ordinary, inspectable authoring unit: a RAES SDL module plus the pack-owned assets, documentation, tests, provenance, parameters, and composition metadata needed to add that infrastructure component to an environment pack. Authors can discover a kit, inspect what it adds, select its parameters and namespace, preview the ordinary file changes, add it to a pack, validate the result, update or replace it, and remove it safely.

This issue is complete when the concrete initial kit collection below and the shared authoring workflow both ship. A one-kit pilot, taxonomy alone, or tooling without useful content is not completion.

Author value

Without kits, an author must repeatedly define common infrastructure, copy or recreate supporting assets, choose identifiers and parameters, wire relationships, add validation, and reconstruct documentation.

With kits, an author starts from working, tested environment components and spends time on the purpose of the environment rather than rebuilding its foundations.

Scope boundary

Issue 190 covers static environment composition and authoring.

It does not own backend realization, host readiness, launch, rollback, teardown, runtime evidence generation, or capability negotiation. It does not modify or extend a backend or adapter. Those responsibilities stay with the backend repositories that implement them. Hub issue #3 is a navigation summary whose false APTL/LilRAE split is being corrected by OpenRAE/hub#39; it is not the authority for repository responsibilities.

It also does not package scenario purpose or participant behavior. Initial kits must not introduce:

• agents or behavior specifications;
• action contracts;
• injects, events, stories, or workflows;
• participant objectives or scenario-specific success conditions;
• offensive, defensive, resilience, research, or product-testing narratives; or
• a supported / constrained / unsupported / unknown backend verdict taxonomy.

The initial collection is limited to infrastructure components with demonstrated working implementations and tests. Missing or speculative primitives belong in follow-up issues, not in this delivery.

Authority

• RAES owns SDL semantics, module descriptors, parameters, exports, namespaces, source-artifact provenance, versions, composition, validation, raes.lock.json, reusable-asset trust policy, and associated-artifact identity and byte binding.
• env-packs owns kit packaging, pack-local assets and metadata, safe authoring operations, deterministic materialization, diagnostics, removal ownership, and projection of ordinary pack files into the existing RAES contracts.
• Catalog repositories own released kit content, admission, versioning, support, archival, and the release inputs consumed by distribution tooling.
• Backends own realization of the resulting ordinary RAES scenario and all runtime evidence.

A kit is not a second SDL, backend profile, runtime plugin, opaque generator, or env-packs-owned dependency lock.

Initial infrastructure kit collection

The following are required deliverables. Implementations may share lower-level assets, but each named kit must remain independently discoverable, inspectable, composable, and removable.

Identity and domain infrastructure

• Windows Active Directory domain controller — configurable forest/domain identity, directory authority, DNS identity, administrator identity, and exported domain-controller node.
• Samba Active Directory-compatible domain controller — configurable AD-compatible domain and directory authority on a Linux/Samba implementation.
• Windows domain member — configurable Windows workstation/server joined to an imported domain authority.
• Linux domain member — configurable Linux host joined to an imported directory/domain authority.
• OIDC identity provider — configurable realm/tenant, users, clients, and exported identity facade suitable for application federation.

Access and workstation infrastructure

• SSH-accessible Linux host — Linux endpoint with declared account and SSH access surface.
• RDP-accessible Windows host — Windows endpoint with declared account and RDP access surface.
• Browser workstation — browser-accessible desktop or terminal workstation for environments needing an inspectable interactive endpoint.

These kits declare environment structure and access endpoints only. Credential brokering and participant-session delivery remain backend responsibilities.

Network and shared services

• Authoritative DNS service — configurable zone, records, and exported DNS service relationships.
• SMB file service — configurable shares, directory-backed or local identities, seeded content, and access relationships.
• SMTP/IMAP mail service — configurable domains, accounts, mailboxes, and seeded messages.
• Webmail service — browser mail client joined to an imported mail service and optional identity provider.
• Static web service — configurable HTTP content service with seeded files and optional TLS identity.
• Application/API service — configurable application endpoint with data/content dependencies and health surface.
• Reverse proxy/API gateway — configurable routed front door for one or more imported application services.

Collaboration and developer services

• Git forge — configurable repositories, users, teams, and seeded project content.
• Issue tracker — configurable projects, users, tickets, and seeded work items.
• Lab portal — configurable landing portal joining selected services into one environment-facing index.

Data and workflow services

• PostgreSQL database — configurable database, roles, schemas, and seeded data.
• S3-compatible object store — configurable buckets, identities, policies, and seeded artifacts.
• Search/index service — configurable indexes, mappings, and seeded documents.
• Notebook environment — configurable notebook server, kernels, data mounts, and imported service relationships.
• Workflow orchestrator — configurable workflows/jobs, service identities, schedules, and imported data/artifact dependencies.

AI and model-development services

• Model registry — configurable models, versions, artifacts, and metadata.
• Text-model serving — configurable local/open model endpoint and model artifact dependency.
• Image-inference service — configurable image model endpoint and artifact/schema dependencies.
• Inference API gateway — configurable front door and policy/routing relationships for imported model services.
• Python package resolver — configurable package index/resolution service and seeded package metadata.
• Isolated Python analysis sandbox — bounded environment for inspecting imported package artifacts.
• Python evaluation worker — configurable worker that consumes imported package/model artifacts and produces bounded result artifacts.

These are environment services only; no adversarial tasks, agent behavior, evaluation objectives, or experiment claims are included.

Security operations infrastructure

• Wazuh security monitoring stack — configurable manager, indexer, dashboard, endpoint-enrollment surfaces, and telemetry relationships.
• Suricata network intrusion-detection sensor — configurable capture and rule inputs plus declared event-output relationships.
• TheHive case-management service — configurable organizations, users, case types, storage, and imported observability relationships.
• Shuffle automation service — configurable platform services, application-integration endpoints, and storage dependencies without scenario-specific response playbooks.

These kits provide the reusable platforms and their static configuration surfaces. They do not include scenario incidents, detections tied to a narrative, response injects, participant behavior, or claims that a backend attached a sensor to live traffic.

Policy and operational services

• Policy engine — configurable policy bundles, decision endpoint, and relationships to imported services.
• Telemetry collector — configurable collection endpoints, routes, and storage/export relationships.
• Observability/evidence store — configurable storage surface for logs, traces, metrics, and other declared artifacts without assigning scenario meaning to them.
• Load/rehearsal runner — configurable workload runner and target relationships; the kit provides infrastructure and invocation assets, not proof that a backend executed a rehearsal.

Kit contract

Define a closed, versioned, pack-owned kit manifest or projection that references rather than restates RAES-owned module facts.

For every kit, inspection must expose:

• kit identity and version;
• author value and intended infrastructure concern;
• RAES module identity;
• parameters and defaults obtained from RAES;
• exported nodes, services, identities, content, and relationships obtained from RAES;
• topology additions and required imports;
• pack-local assets and their visibility;
• resource/cost expectations as pack-domain estimates;
• prerequisites and kit-to-kit dependencies;
• limitations;
• provenance and redistribution terms;
• validation and composition tests; and
• files owned by the materialized kit for conflict-aware update and removal.

raes.lock.json remains the module dependency lock. Do not introduce a competing kit dependency lock or duplicate RAES module descriptors in the kit schema.

Versioning, identity, and supply-chain inputs

Kits and completed packs must consume the existing RAES trust and integrity mechanisms instead of defining parallel pack semantics:

• each kit has a stable identity and release version, and materialization records that exact kit version as inert authoring provenance for inspection, update, replacement, and removal;
• every RAES module selected through a kit is resolved and digest-pinned through raes.lock.json, including the incumbent signature and drift checks;
• every completed pack retains a valid associated-artifact-manifest/v1 whose validator-derived set digest binds the exact pack inventory to its semantic scenario parent;
• shipped or content-addressably pinned components use existing RAES source/artifact identity, version, digest, provenance, and image-attestation fields where those facts belong; the kit manifest must not duplicate them;
• pack-owned provenance continues to record origin, licensing, redistribution, and publication facts for non-RAES material; and
• kit metadata provides deterministic, machine-readable component and artifact inputs sufficient for the distribution workflow to produce a release SBOM without rescanning opaque author intent.

The component-inventory boundary is author-declared but not arbitrary: it must include every executable, container image, package, model, and other software artifact that the kit ships or immutably pins, at the finest authoritative granularity available. External or runtime-selected dependencies must be marked as outside the pack boundary or unresolved rather than guessed. Valid upstream CycloneDX/SPDX documents may be preserved and referenced; they must not be flattened into a falsely complete dependency closure.

Issue #191 owns per-pack SBOM generation, release signatures/attestations, publication, and consumer verification. Issue 190 does not create an SBOM schema, cryptographic format, trust evidence class, pack digest, or signing service. An SBOM is component inventory, not proof of safety, authenticity, or backend realization.

Authoring workflow

Provide one shared library contract and CLI surface that can:

• list and search the kit collection;
• inspect a kit in human-readable and stable machine-readable form;
• select a namespace and bounded parameter values;
• preview topology additions, dependencies, assumptions, files, and lock changes without writing;
• detect namespace, exported-symbol, version, dependency, path, and visibility conflicts;
• atomically add a kit to an existing valid pack;
• immediately validate the completed pack through env-packs and RAES;
• update or replace a kit while preserving and reporting author-modified files; and
• remove a kit using explicit ownership metadata rather than filename or byte guesses.

Interactive, machine-readable, Hub, and future MCP routes must consume these same proposal, composition, diagnostic, and mutation contracts.

Content quality requirements

Every initial kit must:

• provide a coherent author-visible infrastructure capability rather than a thin wrapper around one import;
• contain no scenario narrative or dynamic participant behavior;
• expose bounded, useful parameters and documented exports;
• include required distributable assets and pack-local integration material;
• include documentation, provenance, limitations, resource expectations, and tests;
• validate independently as a module/kit and when composed into a minimal pack;
• compose deterministically under at least two materially different parameter sets where the component supports variation;
• participate in at least one multi-kit composition test;
• support preview, add, validation, update or replacement, and removal; and
• make no backend realization or runtime-evidence claim.

Demonstration

Publish an author walkthrough that:

1. starts with a minimal valid pack;
2. discovers and inspects infrastructure kits;
3. composes a realistic environment from multiple identity, endpoint, network, application, and data kits;
4. previews and reviews the ordinary file, raes.lock.json, associated-artifact, and component-inventory changes;
5. validates the result;
6. changes one kit parameter;
7. replaces one implementation choice where the kit interfaces permit it; and
8. removes one kit cleanly.

The finished pack must remain normal editable source and must validate without the original interactive interface.

Downstream handoff

After the initial kit contracts and stable kit identifiers ship:

• create an issue in Brad-Edwards/shifter to qualify and implement honest BigRAE realization for each published kit, recording concrete gaps per kit; and
• create an issue in Brad-Edwards/aptl—the repository being renamed to LilRAE—to consume and qualify the published kits, recording concrete gaps per kit.

Those issues must enumerate the released kit identifiers. They must not be opened with speculative schemas, and their implementation is not part of issue 190.

Acceptance criteria

• Every kit named in the initial collection is published through the catalog authority.
• Every kit has a stable release identity/version and records exact materialization provenance without creating runtime kit semantics.
• The kit contract references RAES module, source-provenance, trust, and artifact-identity facts without redefining them.
• The initial kits contain environment infrastructure only and no scenario behavior, injects, objectives, or domain-specific narrative.
• Authors can list, search, inspect, preview, add, validate, update or replace, and remove kits through shared library and CLI contracts.
• Preview is side-effect free and shows topology, dependencies, files, assumptions, and RAES lock changes.
• Composition is deterministic, atomic, conflict-aware, and produces ordinary inspectable pack files plus raes.lock.json.
• Every completed pack has a RAES-validated associated-artifact set covering its exact inventory and semantic parent.
• Every kit supplies complete, deterministic inventory inputs for all software artifacts it ships or immutably pins, while explicitly identifying external or unresolved scope.
• Diagnostics identify exact namespace, export, version, dependency, path, visibility, parameter, and author-modification conflicts.
• Every kit has independent validation plus parameter-variation and multi-kit composition coverage where applicable.
• The end-to-end walkthrough composes a realistic multi-service environment and demonstrates modification, replacement, and removal.
• No backend or adapter is modified, launched, probed, or assigned a compatibility verdict by this work.
• Concrete post-release realization issues are created in the two named downstream repositories with the stable kit inventory.
• Separate env-packs backlog issues exist for advanced kits and for high-value infrastructure primitives without demonstrated working implementations.

Non-goals

• Backend implementation, realization envelopes, launch, readiness, teardown, or runtime evidence.
• Dynamic participant behavior, injects, events, objectives, or scenario-specific content.
• Domain-specific security, resilience, research, or product-testing scenarios.
• Speculative infrastructure primitives without a demonstrated working implementation.
• Deep or unbounded module trees.
• A GUI-only authority, hosted runtime, marketplace, or automatic conversion of arbitrary content into kits.

Coordination

Supports OpenRAE/hub#5. The environment kits remain ordinary catalog content; Hub may present the workflow, but files and owning contracts remain authoritative.

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 190-infrastructure-kits, 2026-08-01T17:11:33.539Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #190). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #190). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Implementation plan

1. Publish the kit contracts without extending RAES.

   • Keep ADR 0035 and its index entry as the binding design record.
   • Add closed v1 schemas for a catalog-owned kit manifest, deterministic kit-catalog projection, and inert pack materialization/ownership ledger.
   • Expose only pack-domain facts in those schemas. Module identity, parameters, exports, namespaces, source/artifact provenance, trust, composition, and locks are derived through the exact public RAES 3.2 APIs.
   • Add schema-convention, closed-shape, bounds, secret-shape, and anti-semantic-extension tests first.

2. Build one silent library proposal contract and one CLI over it.

   • Add raes_env_packs.kits with bounded release loading through _pack_fs, stable source/revision identity, list/search/inspect projections, and immutable add/update/replace/remove proposals.
   • Derive module facts by parsing the declared module through RAES. Use RAES structured edits for imports and RAES module-registry APIs for exact local lock records; do not implement a second composer, descriptor parser, or lock.
   • Make preview networkless, non-executing, and free of pack/cache/lock mutation. Human and JSON output, mutation, Hub, and future MCP consumers all use the same proposal and ordered validation.Diagnostic records.
   • Add raes-pack-kit commands for list, search, inspect, preview, add, update, replace, and remove with the existing 0/1/2/3 process-result convention.

3. Make existing-pack mutation transactional and ownership-aware.

   • Factor the wizard's guarded publication primitives into a shared internal transaction helper, preserving its no-replace behavior.
   • For kit changes, capture one descriptor-anchored bounded snapshot, construct a complete successor beside the pack, recheck the source snapshot, validate the successor, and commit with an atomic directory exchange. Never overlay the live pack.
   • Track exact kit/version/namespace/non-secret parameters and explicit file owners with baseline digests. Author-modified owned files block overwrite/deletion; unowned files are never inferred from names or bytes; shared files require explicit multi-owner state.
   • Treat replacement as one remove-plus-add proposal and validate the final RAES imports/references before commit.

4. Preserve pack identity and supply-chain boundaries.

   • Require a materialized successor to retain a valid RAES associated-artifact manifest and semantic parent binding. Recompute changed bytes and the set digest through RAES models; preserve descriptor metadata and supplied upstream SPDX/CycloneDX references rather than flattening them.
   • Record component-inventory references for every shipped or immutably pinned artifact and explicit external/unresolved scope. Do not generate an SBOM, trust claim, signature, safety claim, or realization verdict.
   • Keep raw secrets, secret-like parameter names/values, credentials, signed URLs, environment-variable names, absolute paths, authored values, and raw upstream exceptions out of manifests, ledgers, argv, diagnostics, and output.

5. Publish the complete initial catalog collection.

   • Initialize OpenRAE/reference-packs as the catalog authority and publish all 38 issue-named infrastructure kits as independently versioned, inspectable releases.
   • Each release includes a substantive RAES module, bounded parameters/exports, declared associated files when needed, provenance/licensing/limitations/resource expectations, component-inventory scope, and tests. Content remains static infrastructure only.
   • Catalog CI validates every release independently, exercises two parameter sets where meaningful, and composes representative identity, endpoint, application/data, AI, and security-operations combinations. The catalog contains no backend code or compatibility verdict taxonomy.
   • Open a separate catalog PR linked to issue 190; stable released identifiers become the authoritative list for the later realization issues.

6. Document and demonstrate the author journey.

   • Update the normative pack layout and public docs for kit discovery, inspection, proposal fields, materialization ownership, conflict handling, and security boundaries.
   • Add an integration runbook and executable walkthrough starting from a minimal content-identified pack, then inspect, preview, compose multiple kits, validate, change a parameter, replace an implementation, remove a kit, and validate the remaining ordinary pack without the interactive interface.

7. Verification and completion.

   • Use red-green TDD for every issue acceptance criterion: schema rejection, discovery determinism, RAES fact derivation, side-effect-free preview, all conflict domains, secret rejection, atomic failure preservation, author-modification protection, update/replace/remove, exact lock and associated-artifact changes, parameter variation, and multi-kit composition.
   • Run targeted kit/transaction/catalog tests during implementation, then the repository completion/policy gates. Validate the full catalog with the released CLI and its own independent/multi-kit tests.
   • Do not edit pyproject.toml version or CHANGELOG.md; use a feat: PR title so Release Please owns the version decision.
   • After both PRs merge and stable kit identifiers exist, create the issue-required Shifter and APTL realization-qualification issues using the released identifier list. Existing env-packs backlog issues 224 and 225 satisfy the two deferred-content criteria.

Whole-repository design check

• Security: _pack_fs owns safe reads and path/collision bounds; closed schemas and strict YAML own input shape; the kit library rejects secret-bearing inputs; RAES owns semantic/trust/lock validation; Diagnostic owns bounded error output; the shared transaction helper owns filesystem replacement; associated-artifact validation owns exact byte identity.
• Maintainability: reuse wizard.py proposal/preview conventions, catalog.py source identity and deterministic JSON patterns, validation.py schemas/limits/diagnostics/static author mode, digest.py RAES bindings, and check.py CLI outcomes. Add no plugin registry, second lock, second SDL, or executable hook.
• Extensibility: version the manifest, catalog projection, and ledger independently; keep a closed operation vocabulary and explicit resource limits; later catalog providers or front ends consume the same DTOs without product fields or recomputing composition.
• Whole-repo surfaces: package entry points, resource schemas, normative contract, validation, content/release identity, wizard transactions, public API exports, tests, docs, packaged-resource inclusion, and both repository completion/policy suites move together.

[Brad-Edwards]

Acceptance-clause implementation map

1. All named kits published: feat: publish initial infrastructure kit collection reference-packs#2 contains 38 independently discoverable releases and its catalog test asserts the exact count.
2. Stable identity/version and inert provenance: kit.schema.yaml defines the closed release carrier; kit-materializations.schema.yaml records exact kit/source identities and versions; kits.py projects them only into authoring provenance.
3. RAES authority preserved: ADR 0035 and docs/public/kits.md define the boundary; load_kit_release() derives module facts through RAES and validates the RAES associated-artifact manifest rather than restating SDL, trust, lock, or artifact semantics.
4. Infrastructure-only content: kits.py rejects agents, behavior specifications, action contracts, conditions, objectives, injects, events, scripts, stories, and workflows. The catalog content strategy and tests enforce static infrastructure scope.
5. Shared library and CLI: public functions in kits.py and the raes-pack-kit commands in kit_cli.py cover list, search, inspect, preview/add, update, replace, and remove. All CLI mutations consume the same proposal/apply contract.
6. Side-effect-free preview: proposal_document() exposes topology, dependencies, assumptions, files, diagnostics, and lock changes without values; test_preview_is_networkless_side_effect_free_and_value_free verifies no write occurs.
7. Deterministic atomic ordinary composition: _transactions.py uses atomic no-replace/exchange primitives; apply_proposal() revalidates the exact staged successor and restores the original on races or post-exchange failure. Materialization tests cover add, update, replace, remove, ownership, and rollback.
8. Exact RAES artifact identity: _refresh_associated_artifacts() rebuilds and RAES-validates the completed pack's exact inventory. Materialization tests and the walkthrough revalidate the set digest and semantic parent after every operation.
9. Deterministic component inputs: the kit contract requires closed component_inventory entries with authoritative shipped/pinned facts or explicit external/unresolved scope. All 38 catalog releases declare them and bind every release file.
10. Exact diagnostics: propose_add() and removal/update paths emit stable codes for namespace, export, version, dependency, path, visibility, parameter, source, and author-modification conflicts; test_conflict_diagnostics_cover_each_authoring_domain and focused dependency/ownership tests cover them.
11. Independent and composed coverage: feat: publish initial infrastructure kit collection reference-packs#2 validates every release under default and materially different domain parameters, requires substantive seed/integration content, and composes a representative multi-kit environment.
12. End-to-end walkthrough: tests_integration/kit_author_walkthrough.py performs discovery/inspection, five-kit composition, preview, exact lock/artifact validation, parameter update, implementation replacement, removal, and final ordinary pack release validation (25 checks pass). The runbook documents execution and boundaries.
13. No backend work or verdict: ADR 0035, public docs, catalog content strategy, and the walkthrough explicitly exclude realization, launch, probing, evidence, and compatibility verdicts. No backend repository is modified by this implementation.
14. Concrete downstream handoffs: feat(raes): qualify additional released infrastructure kits as needed Brad-Edwards/shifter#1949 and Consume the released infrastructure kits through the normal pack path Brad-Edwards/aptl#894 enumerate all 38 stable kit identifiers and scope honest realization/consumption qualification as later work.
15. Separate backlog: consider(kits): plan advanced behavioral and domain-specific kit families #224 tracks advanced/domain-specific families; feat(kits): add missing infrastructure kits #225 tracks broadly useful infrastructure primitives that do not yet have demonstrated working implementations.

Verification completed locally:

• 671 unit tests passed
• environment-pack content CI passed
• release gate passed
• source/test/integration compilation passed
• catalog tests passed for all 38 releases
• executable author walkthrough: 25 passed, 0 failed