From 5f610f6449f5e7250e92f45f259151bd68d929ff Mon Sep 17 00:00:00 2001 From: "Alex G. Wolff" <13754094+alexgwolff@users.noreply.github.com> Date: Sat, 19 Sep 2026 17:41:44 -0300 Subject: [PATCH 01/15] docs: add spec pattern and docs for environment module Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com> --- .gitignore | 1 + SPECIFICATIONS.md | 172 +++++ src/environment/src/env_var/README.md | 77 ++ .../env-var-declarations.acceptance.md | 156 ++++ .../env-var-declarations.spec.md | 92 +++ .../env-var-host/env-var-host.acceptance.md | 108 +++ .../docs/env-var-host/env-var-host.spec.md | 54 ++ .../src/env_var/docs/env-var-intent.md | 79 ++ .../env-var-projection.acceptance.md | 85 +++ .../env-var-projection.spec.md | 53 ++ .../env-var-resolution.acceptance.md | 688 ++++++++++++++++++ .../env-var-resolution.spec.md | 224 ++++++ 12 files changed, 1789 insertions(+) create mode 100644 SPECIFICATIONS.md create mode 100644 src/environment/src/env_var/README.md create mode 100644 src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md create mode 100644 src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md create mode 100644 src/environment/src/env_var/docs/env-var-host/env-var-host.acceptance.md create mode 100644 src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md create mode 100644 src/environment/src/env_var/docs/env-var-intent.md create mode 100644 src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md create mode 100644 src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md create mode 100644 src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.acceptance.md create mode 100644 src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md diff --git a/.gitignore b/.gitignore index f423f41..c840149 100644 --- a/.gitignore +++ b/.gitignore @@ -75,4 +75,5 @@ !/README.md !/AGENTS.md !/BUILDING.md +!/SPECIFICATIONS.md !/LICENSE diff --git a/SPECIFICATIONS.md b/SPECIFICATIONS.md new file mode 100644 index 0000000..f336bf6 --- /dev/null +++ b/SPECIFICATIONS.md @@ -0,0 +1,172 @@ +--- +title: Specifications +summary: Conventions for documenting feature intent, requirements, and acceptance scenarios. +tags: [specification, requirements, acceptance, ears, documentation] +--- + +## Purpose + +This document defines how Kraf records feature intent, behavioral requirements, +and acceptance scenarios. + +It defines the documentation protocol, not the behavior of a specific feature. + +## Document types + +### Intent + +An intent explains why a feature exists, the problem it addresses, its +boundaries, and its non-goals. It is not normative. + +### Specification + +A specification defines normative, traceable behavioral requirements. Each +requirement has a stable identifier, a name, statuses, and links to its +acceptance scenarios. + +### Acceptance + +An acceptance document defines observable scenarios derived from requirements. +Scenarios use embedded Gherkin and link back to the requirement they verify. + +## Traceability + +```text +Intent → Requirement ↔ Acceptance +``` + +A requirement may have multiple acceptance scenarios. An acceptance scenario +belongs to one primary requirement. + +## Feature-local layout + +Documentation lives with the feature it describes. + +```text +/ +└── docs/ + ├── -intent.md + └── / + ├── .spec.md + └── .acceptance.md +``` + +Documentation does not need to map one-to-one to source files, platform files, +or tests. Create a document when a domain behavior needs a durable contract. + +## Identifiers + +Identifiers use an uppercase feature area, followed by a type and a four-digit +sequence number. + +```text +_-FEAT-0001 +_-REQ-0001 +_-ACC-0001 +``` + +For example: + +```text +ENV_VAR_DECLARATIONS-REQ-0001 +ENV_VAR_DECLARATIONS-ACC-0001 +``` + +## Normative language + +Specifications use EARS notation and the normative terms defined by RFC 2119 +and RFC 8174. + +- **SHALL** and **SHALL NOT** define mandatory behavior. +- **SHOULD** and **SHOULD NOT** define expected behavior that requires an + explicit justification to deviate from. +- **MAY** defines optional behavior. + +Use the EARS pattern that matches the behavior: + +```text +The software SHALL . + +WHEN , +THE SOFTWARE SHALL . + +IF , +THEN THE SOFTWARE SHALL . +``` + +## Statuses + +Each requirement declares three independent statuses: + +- **Requirement status:** `Draft`, `Accepted`, or `Superseded`. +- **Implementation status:** `Not implemented`, `Partially implemented`, or + `Implemented`. +- **Verification status:** `Not verified` or `Verified`. + +Each acceptance scenario declares its own acceptance and verification status. +Implementation status belongs to the requirement, not to each scenario. + +## Minimal example + +An intent establishes the boundary: + +```md +## Intent + +The feature must make process configuration explicit rather than inheriting +undeclared host state. +``` + +A specification defines a requirement and links to acceptance evidence: + +```md +### EXAMPLE_AREA-REQ-0001 + +Name: Explicit configuration + +**Links:** + +- [EXAMPLE_AREA-ACC-0001](./example.acceptance.md#example_area-acc-0001) + +**Status**: + +- Requirement status: Draft +- Implementation status: Not implemented +- Verification status: Not verified + +**WHEN:** Configuration provides an unknown key, + +**THE SOFTWARE SHALL:** reject the configuration. +``` + +Acceptance links back and states the observable behavior: + +````md +## EXAMPLE_AREA-ACC-0001 + +Name: Unknown configuration key is rejected + +**Links:** + +- [EXAMPLE_AREA-REQ-0001](./example.spec.md#example_area-req-0001) + +```gherkin +Feature: EXAMPLE_AREA-FEAT-0001 — Explicit configuration + + Rule: EXAMPLE_AREA-REQ-0001 — Explicit configuration + + Scenario: EXAMPLE_AREA-ACC-0001 — Unknown configuration key is rejected + Given no declaration exists for "EXAMPLE_KEY" + When configuration provides a value for "EXAMPLE_KEY" + Then the software rejects the configuration +``` +```` + +## Current reference + +The environment-variable feature is the current reference implementation of +this convention: + +- [Environment variable intent](./src/environment/src/env_var/docs/env-var-intent.md) +- [Environment variable declarations specification](./src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md) +- [Environment variable declarations acceptance](./src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md) diff --git a/src/environment/src/env_var/README.md b/src/environment/src/env_var/README.md new file mode 100644 index 0000000..14a6ed3 --- /dev/null +++ b/src/environment/src/env_var/README.md @@ -0,0 +1,77 @@ +--- +title: Environment variables +summary: Declarative model, resolution, and projection of environment variables in Kraf. +tags: [environment, env var, resolution, projection] +--- + +This module defines and resolves Kraf's declarative model for environment +variables: their sources (host, organization, user, project, and session), +aliases, and projections exported to Kraf-managed processes. + +> **Note:** this document describes Kraf's environment-variable model, including +> concepts and sources planned for its evolution. It does not imply that all of +> these capabilities are already implemented. + +## Concepts + +- [**Sources**](#sources): where environment-variable values, configuration, and + restrictions come from. +- [**Declaration**](#declarations): the canonical definition of a variable. +- [**Resolver**](#resolution): the component that applies declarations to values + from sources to produce an effective value. +- [**Projection**](#projection): the set of effective variables that Kraf + exports to a managed process. + +### Sources + +- **Host:** provides values available in the current environment and platform. +- **User:** provides persistent personal preferences. +- **Organization:** provides shared configuration and policies enforced by the + organization. +- **Project:** provides versioned, project-specific configuration. +- **Session:** provides ephemeral values controlled by Kraf. + +### Declarations + +A canonical definition of a variable in Kraf. A declaration specifies: + +- its canonical key; +- import and export aliases; +- sources eligible to provide a value; +- resolution strategy; +- fallback; +- keys that may be projected to a child process. + +### Resolution + +The resolver applies declarations to values available from sources and produces +the effective value of each variable. + +For each declaration, it defines: + +- precedence between sources; +- how values are combined, when applicable; +- how conflicts or missing values are handled; +- when a fallback is applied; +- how placeholders in values and fallbacks are expanded. + +### Projection + +A projection is the set of effective variables exported by Kraf to a managed +process. + +A declaration can produce one internal canonical key and zero or more export +keys. Not every resolved value must be projected to a child process. + +## Documentation + +- [Intent](./docs/env-var-intent.md): purpose, boundaries, and evolution of this + module. +- [Declarations](./docs/env-var-declarations/env-var-declarations.spec.md): + declaration requirements and acceptance scenarios. +- [Resolution](./docs/env-var-resolution/env-var-resolution.spec.md): resolution + requirements and acceptance scenarios. +- [Projection](./docs/env-var-projection/env-var-projection.spec.md): projection + requirements and acceptance scenarios. +- [Host mappings](./docs/env-var-host/env-var-host.spec.md): platform mapping + requirements and acceptance scenarios. diff --git a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md new file mode 100644 index 0000000..a27df15 --- /dev/null +++ b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md @@ -0,0 +1,156 @@ +# Environment variables declaration — Acceptance + +## ENV_VAR_DECLARATIONS-ACC-0001 + +Name: Unknown runtime declaration is rejected + +**Links:** + +- [ENV_VAR_DECLARATIONS-REQ-0001](./env-var-declarations.spec.md#env_var_declarations-req-0001) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations + + Rule: ENV_VAR_DECLARATIONS-REQ-0001 — Static declaration + + Scenario: ENV_VAR_DECLARATIONS-ACC-0001 — Unknown runtime declaration is rejected + Given no declaration exists for "EXAMPLE_TOKEN" + When runtime configuration provides a value for "EXAMPLE_TOKEN" + Then the software rejects the configuration + And "EXAMPLE_TOKEN" is not projected to a managed process +``` + +--- + +## ENV_VAR_DECLARATIONS-ACC-0002 + +Name: Known runtime declaration accepts a value + +**Links:** + +- [ENV_VAR_DECLARATIONS-REQ-0001](./env-var-declarations.spec.md#env_var_declarations-req-0001) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations + + Rule: ENV_VAR_DECLARATIONS-REQ-0001 — Static declaration + + Scenario: ENV_VAR_DECLARATIONS-ACC-0002 — Known runtime declaration accepts a value + Given a declaration exists for "EXAMPLE_TOKEN" + When runtime configuration provides a value for "EXAMPLE_TOKEN" + Then the software accepts the configuration +``` + +--- + +## ENV_VAR_DECLARATIONS-ACC-0003 + +Name: Duplicate canonical key is rejected + +**Links:** + +- [ENV_VAR_DECLARATIONS-REQ-0002](./env-var-declarations.spec.md#env_var_declarations-req-0002) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations + + Rule: ENV_VAR_DECLARATIONS-REQ-0002 — Canonical key uniqueness + + Scenario: ENV_VAR_DECLARATIONS-ACC-0003 — Duplicate canonical key is rejected + Given two declarations use the canonical key "EXAMPLE_TOKEN" + When the software loads the declaration set + Then the software rejects the declaration set +``` + +--- + +## ENV_VAR_DECLARATIONS-ACC-0004 + +Name: Merge mapping declares multiple import aliases + +**Links:** + +- [ENV_VAR_DECLARATIONS-REQ-0003](./env-var-declarations.spec.md#env_var_declarations-req-0003) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations + + Rule: ENV_VAR_DECLARATIONS-REQ-0003 — Mapping mode validity + + Scenario: ENV_VAR_DECLARATIONS-ACC-0004 — Merge mapping declares multiple import aliases + Given a declaration uses merge import mode + When the declaration defines fewer than two import aliases + Then the software rejects the declaration +``` + +--- + +## ENV_VAR_DECLARATIONS-ACC-0005 + +Name: Pass-through mapping imports only its canonical key + +**Links:** + +- [ENV_VAR_DECLARATIONS-REQ-0003](./env-var-declarations.spec.md#env_var_declarations-req-0003) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations + + Rule: ENV_VAR_DECLARATIONS-REQ-0003 — Mapping mode validity + + Scenario: ENV_VAR_DECLARATIONS-ACC-0005 — Pass-through mapping imports only its canonical key + Given a declaration uses pass-through import mode + When the declaration imports an alias other than its canonical key + Then the software rejects the declaration +``` + +--- + +## ENV_VAR_DECLARATIONS-ACC-0006 + +Name: Pass-through mapping has no fallback + +**Links:** + +- [ENV_VAR_DECLARATIONS-REQ-0003](./env-var-declarations.spec.md#env_var_declarations-req-0003) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations + + Rule: ENV_VAR_DECLARATIONS-REQ-0003 — Mapping mode validity + + Scenario: ENV_VAR_DECLARATIONS-ACC-0006 — Pass-through mapping has no fallback + Given a declaration uses pass-through import mode + When the declaration defines a fallback + Then the software rejects the declaration +``` diff --git a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md new file mode 100644 index 0000000..4d8af85 --- /dev/null +++ b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md @@ -0,0 +1,92 @@ +--- +title: Environment variables declaration - SPEC +summary: Requirements for declaring environment variables. +tags: [environment, env-var, specification, spec, declaration] +status: draft +--- + +> [!IMPORTANT] +> Requirements in this specification use EARS notation. **SHALL** and **SHALL +> NOT** define mandatory behavior; **SHOULD** and **SHOULD NOT** define expected +> behavior that requires an explicit justification to deviate from; **MAY** +> defines optional behavior. +> +> These terms follow RFC 2119 and RFC 8174. + +## Requirements + +### ENV_VAR_DECLARATIONS-REQ-0001 + +Name: Static declaration + +**Links:** + +- [ENV_VAR_DECLARATIONS-ACC-0001](./env-var-declarations.acceptance.md#env_var_declarations-acc-0001) +- [ENV_VAR_DECLARATIONS-ACC-0002](./env-var-declarations.acceptance.md#env_var_declarations-acc-0002) + +**Status**: + +- Requirement status: Draft +- Implementation status: Not implemented +- Verification status: Not verified + +**SHALL:** The software resolves and projects only environment-variable +declarations that are built into the software or packaged as immutable metadata +with a plugin. + +**MAY:** Runtime configuration provides values for known declarations. + +**SHALL NOT:** Runtime configuration creates declarations or adds import +aliases, export aliases, or source eligibility. + +**WHEN:** Runtime configuration provides a value for an unknown declaration, + +**THE SOFTWARE SHALL:** reject the configuration. + +--- + +### ENV_VAR_DECLARATIONS-REQ-0002 + +Name: Canonical key uniqueness + +**Links:** + +- [ENV_VAR_DECLARATIONS-ACC-0003](./env-var-declarations.acceptance.md#env_var_declarations-acc-0003) + +**Status**: + +- Requirement status: Draft +- Implementation status: Partially implemented +- Verification status: Not verified + +**SHALL:** The software accepts at most one declaration for each canonical key. + +**WHEN:** A declaration set contains duplicate canonical keys, + +**THE SOFTWARE SHALL:** reject the declaration set. + +--- + +### ENV_VAR_DECLARATIONS-REQ-0003 + +Name: Mapping mode validity + +**Links:** + +- [ENV_VAR_DECLARATIONS-ACC-0004](./env-var-declarations.acceptance.md#env_var_declarations-acc-0004) +- [ENV_VAR_DECLARATIONS-ACC-0005](./env-var-declarations.acceptance.md#env_var_declarations-acc-0005) +- [ENV_VAR_DECLARATIONS-ACC-0006](./env-var-declarations.acceptance.md#env_var_declarations-acc-0006) + +**Status**: + +- Requirement status: Draft +- Implementation status: Partially implemented +- Verification status: Not verified + +**SHALL:** A declaration using merge import mode declares at least two import +aliases. + +**SHALL:** A declaration using pass-through import mode declares only its +canonical key as an import alias. + +**SHALL NOT:** A declaration using pass-through import mode declares a fallback. diff --git a/src/environment/src/env_var/docs/env-var-host/env-var-host.acceptance.md b/src/environment/src/env_var/docs/env-var-host/env-var-host.acceptance.md new file mode 100644 index 0000000..6e9d558 --- /dev/null +++ b/src/environment/src/env_var/docs/env-var-host/env-var-host.acceptance.md @@ -0,0 +1,108 @@ +--- +title: Environment variables host mappings - Acceptance +summary: Acceptance scenarios for platform-specific environment-variable mappings. +tags: [environment, env-var, acceptance, host, platform, gherkin] +status: draft +--- + +## ENV_VAR_HOST-ACC-0001 + +Name: Every shared canonical key has a Linux mapping + +**Links:** + +- [ENV_VAR_HOST-REQ-0001](./env-var-host.spec.md#env_var_host-req-0001) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_HOST-FEAT-0001 — Environment variable host mappings + + Rule: ENV_VAR_HOST-REQ-0001 — Supported-platform mapping completeness + + Scenario: ENV_VAR_HOST-ACC-0001 — Every shared canonical key has a Linux mapping + Given the shared canonical environment-variable keys + When the Linux mappings are loaded + Then every shared canonical key has a Linux mapping +``` + +--- + +## ENV_VAR_HOST-ACC-0002 + +Name: Every shared canonical key has a macOS mapping + +**Links:** + +- [ENV_VAR_HOST-REQ-0001](./env-var-host.spec.md#env_var_host-req-0001) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_HOST-FEAT-0001 — Environment variable host mappings + + Rule: ENV_VAR_HOST-REQ-0001 — Supported-platform mapping completeness + + Scenario: ENV_VAR_HOST-ACC-0002 — Every shared canonical key has a macOS mapping + Given the shared canonical environment-variable keys + When the macOS mappings are loaded + Then every shared canonical key has a macOS mapping +``` + +--- + +## ENV_VAR_HOST-ACC-0003 + +Name: Every shared canonical key has a Windows mapping + +**Links:** + +- [ENV_VAR_HOST-REQ-0001](./env-var-host.spec.md#env_var_host-req-0001) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_HOST-FEAT-0001 — Environment variable host mappings + + Rule: ENV_VAR_HOST-REQ-0001 — Supported-platform mapping completeness + + Scenario: ENV_VAR_HOST-ACC-0003 — Every shared canonical key has a Windows mapping + Given the shared canonical environment-variable keys + When the Windows mappings are loaded + Then every shared canonical key has a Windows mapping +``` + +--- + +## ENV_VAR_HOST-ACC-0004 + +Name: Home and work-directory declarations use provided values + +**Links:** + +- [ENV_VAR_HOST-REQ-0002](./env-var-host.spec.md#env_var_host-req-0002) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_HOST-FEAT-0001 — Environment variable host mappings + + Rule: ENV_VAR_HOST-REQ-0002 — Session-owned directory sources + + Scenario: ENV_VAR_HOST-ACC-0004 — Home and work-directory declarations use provided values + Given a supported platform mapping + When the mapping declares WORKDIR or a HOME family key + Then the declaration source is provided +``` diff --git a/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md b/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md new file mode 100644 index 0000000..4c4b7a0 --- /dev/null +++ b/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md @@ -0,0 +1,54 @@ +--- +title: Environment variables host mappings - SPEC +summary: Requirements for platform-specific environment-variable mappings. +tags: [environment, env-var, specification, spec, host, platform] +status: draft +--- + +> [!IMPORTANT] +> Requirements in this specification use EARS notation. **SHALL** and **SHALL +> NOT** define mandatory behavior; **SHOULD** and **SHOULD NOT** define expected +> behavior that requires an explicit justification to deviate from; **MAY** +> defines optional behavior. +> +> These terms follow RFC 2119 and RFC 8174. + +## Requirements + +### ENV_VAR_HOST-REQ-0001 + +Name: Supported-platform mapping completeness + +**Links:** + +- [ENV_VAR_HOST-ACC-0001](./env-var-host.acceptance.md#env_var_host-acc-0001) +- [ENV_VAR_HOST-ACC-0002](./env-var-host.acceptance.md#env_var_host-acc-0002) +- [ENV_VAR_HOST-ACC-0003](./env-var-host.acceptance.md#env_var_host-acc-0003) + +**Status**: + +- Requirement status: Draft +- Implementation status: Implemented +- Verification status: Not verified + +**SHALL:** Every supported platform mapping declares every shared canonical +environment-variable key. + +--- + +### ENV_VAR_HOST-REQ-0002 + +Name: Session-owned directory sources + +**Links:** + +- [ENV_VAR_HOST-ACC-0004](./env-var-host.acceptance.md#env_var_host-acc-0004) + +**Status**: + +- Requirement status: Draft +- Implementation status: Implemented +- Verification status: Not verified + +**SHALL:** The WORKDIR and HOME declaration families use provided values rather +than values imported from the host. diff --git a/src/environment/src/env_var/docs/env-var-intent.md b/src/environment/src/env_var/docs/env-var-intent.md new file mode 100644 index 0000000..2aeb06c --- /dev/null +++ b/src/environment/src/env_var/docs/env-var-intent.md @@ -0,0 +1,79 @@ +--- +title: Environment variables intent +summary: Why Kraf resolves and projects environment variables through a declarative model. +tags: [environment, env-var, intent, security, projection] +--- + +## Problem + +Development environments inherit a large, implicit set of environment variables +from the host. Their names, formats, availability, and meaning vary across +platforms. Values may also come from personal preferences, project +configuration, organization policy, or the current Kraf session. + +When each tool or module reads the host environment directly, the resulting +behavior is difficult to understand, reproduce, audit, and evolve. It also +allows undeclared host state to reach managed processes by accident. + +## Intent + +This module should resolve environment variables through one declarative model +and produce an explicit projection for each managed process. + +The model must make it possible to: + +- normalize platform-specific aliases behind canonical declarations; +- combine values from Host, User, Organization, Project, and Session sources; +- evolve source loading and resolution rules without spreading environment logic + across consumers; +- make the environment received by a managed process explicit and reviewable. + +## Principles + +### Static declarations + +Environment declarations are static capabilities. + +Declarations are embedded in source code. Plugin declarations are embedded in +plugin source code or immutable plugin metadata distributed with the plugin. A +declaration identifies an allowed variable and its behavior; it does not contain +the final runtime value. + +Dynamic sources may provide values for existing declarations. They must not +create new declarations, request undeclared host values, or expand the set of +variables that a process may receive. + +### Security access + +Only the environment module may read raw environment values from the host. + +Other modules and plugins may obtain a resolved value only through a declaration +they own or explicitly declare as a dependency. This module must not expose an +operation that enumerates all host environment variables, nor arbitrary +string-based host lookups outside this module. + +### Explicit projection + +Importing an alias and exporting a value are separate permissions. + +Knowing that a host alias exists does not authorize exporting it. Resolving a +value does not authorize projecting it. A managed process receives only the +canonical keys and export aliases explicitly permitted by declarations. + +This makes the projected environment an allowlist rather than an inherited copy +of the host environment. + +## Boundaries + +This module owns declaration, resolution, and projection of environment values. + +It does not: + +- create or manage process sessions; +- choose a terminal or launch a process; +- sandbox filesystem, network, permissions, or host processes; +- define every future source format or precedence rule. + +Session creation and process launch belong to the trap module. The trap provides +session-owned values, requests a resolved projection, and applies that +projection to its managed process. diff --git a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md new file mode 100644 index 0000000..9f7a250 --- /dev/null +++ b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md @@ -0,0 +1,85 @@ +--- +title: Environment variables projection - Acceptance +summary: Acceptance scenarios for projecting environment variables. +tags: [environment, env-var, acceptance, projection, gherkin] +status: draft +--- + +## ENV_VAR_PROJECTION-ACC-0001 + +Name: Declared export alias is projected + +**Links:** + +- [ENV_VAR_PROJECTION-REQ-0001](./env-var-projection.spec.md#env_var_projection-req-0001) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_PROJECTION-FEAT-0001 — Environment variable projection + + Rule: ENV_VAR_PROJECTION-REQ-0001 — Explicit export authorization + + Scenario: ENV_VAR_PROJECTION-ACC-0001 — Declared export alias is projected + Given "EXAMPLE_TOKEN" is declared as an export alias + And "EXAMPLE_TOKEN" has a resolved value + When the software applies the projection to a managed process + Then the managed process receives "EXAMPLE_TOKEN" +``` + +--- + +## ENV_VAR_PROJECTION-ACC-0002 + +Name: Non-exportable resolved value is not projected + +**Links:** + +- [ENV_VAR_PROJECTION-REQ-0001](./env-var-projection.spec.md#env_var_projection-req-0001) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_PROJECTION-FEAT-0001 — Environment variable projection + + Rule: ENV_VAR_PROJECTION-REQ-0001 — Explicit export authorization + + Scenario: ENV_VAR_PROJECTION-ACC-0002 — Non-exportable resolved value is not projected + Given "INTERNAL_TOKEN" has a resolved value + And "INTERNAL_TOKEN" is not declared as an export alias + When the software applies the projection to a managed process + Then the managed process does not receive "INTERNAL_TOKEN" +``` + +--- + +## ENV_VAR_PROJECTION-ACC-0003 + +Name: Export aliases receive the canonical resolved value + +**Links:** + +- [ENV_VAR_PROJECTION-REQ-0002](./env-var-projection.spec.md#env_var_projection-req-0002) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_PROJECTION-FEAT-0001 — Environment variable projection + + Rule: ENV_VAR_PROJECTION-REQ-0002 — Export value symmetry + + Scenario: ENV_VAR_PROJECTION-ACC-0003 — Export aliases receive the canonical resolved value + Given "HOME_TEMP" resolves to "/workspace/.tmp" + And "TMPDIR" is an export alias of "HOME_TEMP" + When the software resolves the declaration + Then "TMPDIR" resolves to "/workspace/.tmp" +``` diff --git a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md new file mode 100644 index 0000000..b0168a8 --- /dev/null +++ b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md @@ -0,0 +1,53 @@ +--- +title: Environment variables projection - SPEC +summary: Requirements for projecting resolved environment variables to managed processes. +tags: [environment, env-var, specification, spec, projection] +status: draft +--- + +> [!IMPORTANT] +> Requirements in this specification use EARS notation. **SHALL** and **SHALL +> NOT** define mandatory behavior; **SHOULD** and **SHOULD NOT** define expected +> behavior that requires an explicit justification to deviate from; **MAY** +> defines optional behavior. +> +> These terms follow RFC 2119 and RFC 8174. + +## Requirements + +### ENV_VAR_PROJECTION-REQ-0001 + +Name: Explicit export authorization + +**Links:** + +- [ENV_VAR_PROJECTION-ACC-0001](./env-var-projection.acceptance.md#env_var_projection-acc-0001) +- [ENV_VAR_PROJECTION-ACC-0002](./env-var-projection.acceptance.md#env_var_projection-acc-0002) + +**Status**: + +- Requirement status: Draft +- Implementation status: Implemented +- Verification status: Not verified + +**SHALL:** The software projects only keys declared as export aliases by the +active mappings. + +--- + +### ENV_VAR_PROJECTION-REQ-0002 + +Name: Export value symmetry + +**Links:** + +- [ENV_VAR_PROJECTION-ACC-0003](./env-var-projection.acceptance.md#env_var_projection-acc-0003) + +**Status**: + +- Requirement status: Draft +- Implementation status: Implemented +- Verification status: Not verified + +**SHALL:** Every export alias produced by a declaration has the declaration's +resolved value. diff --git a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.acceptance.md b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.acceptance.md new file mode 100644 index 0000000..872dd33 --- /dev/null +++ b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.acceptance.md @@ -0,0 +1,688 @@ +--- +title: Environment variables resolution - Acceptance +summary: Acceptance scenarios for environment-variable resolution. +tags: [environment, env-var, acceptance, resolution, gherkin] +status: draft +--- + +## ENV_VAR_RESOLUTION-ACC-0001 + +Name: Import aliases are collected and deduplicated + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0001](./env-var-resolution.spec.md#env_var_resolution-req-0001) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0001 — Declared import dependency collection + + Scenario: ENV_VAR_RESOLUTION-ACC-0001 — Import aliases are collected and deduplicated + Given multiple declarations import the alias "SHELL" + When the software collects import dependencies + Then "SHELL" is collected once +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0002 + +Name: Fallback variable reference is collected + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0001](./env-var-resolution.spec.md#env_var_resolution-req-0001) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0001 — Declared import dependency collection + + Scenario: ENV_VAR_RESOLUTION-ACC-0002 — Fallback variable reference is collected + Given a declaration fallback references "$HOME" + When the software collects import dependencies + Then "HOME" is collected +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0003 + +Name: First available import alias is selected + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0002](./env-var-resolution.spec.md#env_var_resolution-req-0002) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0002 — First-found resolution + + Scenario: ENV_VAR_RESOLUTION-ACC-0003 — First available import alias is selected + Given a declaration imports "USER_LANGUAGE" before "LANG" + And both aliases provide a value + When the software resolves the declaration + Then the value of "USER_LANGUAGE" is selected +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0004 + +Name: Fallback is used when no import alias has a value + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0002](./env-var-resolution.spec.md#env_var_resolution-req-0002) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0002 — First-found resolution + + Scenario: ENV_VAR_RESOLUTION-ACC-0004 — Fallback is used when no import alias has a value + Given no import alias provides a value + And the declaration fallback is "C.UTF-8" + When the software resolves the declaration + Then the declaration resolves to "C.UTF-8" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0005 + +Name: Non-empty path aliases are merged in declaration order + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env_var_resolution-req-0003) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0003 — Path merge resolution + + Scenario: ENV_VAR_RESOLUTION-ACC-0005 — Non-empty path aliases are merged in declaration order + Given a declaration imports "BIN_A" before "BIN_B" + And "BIN_A" provides "/custom/bin" + And "BIN_B" provides "/usr/bin" + When the software resolves the declaration + Then the resolved value contains "/custom/bin" before "/usr/bin" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0006 + +Name: Merge fallback is used when no path is available + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env_var_resolution-req-0003) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0003 — Path merge resolution + + Scenario: ENV_VAR_RESOLUTION-ACC-0006 — Merge fallback is used when no path is available + Given no import alias provides a non-empty path value + And the declaration fallback is "/usr/share/man" + When the software resolves the declaration + Then the declaration resolves to "/usr/share/man" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0007 + +Name: Tilde fallback expands from resolved home + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + + Scenario: ENV_VAR_RESOLUTION-ACC-0007 — Tilde fallback expands from resolved home + Given "HOME" resolves to "/workspace" + And a declaration fallback is "~/.cache" + When the software resolves the declaration + Then the declaration resolves to "/workspace/.cache" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0008 + +Name: Dollar fallback expands from a collected value + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + + Scenario: ENV_VAR_RESOLUTION-ACC-0008 — Dollar fallback expands from a collected value + Given "HOME" has the collected value "/workspace" + And a declaration fallback is "$HOME/.cache" + When the software resolves the declaration + Then the declaration resolves to "/workspace/.cache" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0009 + +Name: Unresolved placeholder remains literal + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + + Scenario: ENV_VAR_RESOLUTION-ACC-0009 — Unresolved placeholder remains literal + Given a declaration fallback is "$UNKNOWN/.cache" + And "UNKNOWN" has no resolved value + When the software resolves the declaration + Then the declaration resolves to "$UNKNOWN/.cache" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0010 + +Name: Empty first-found value is selected + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0002](./env-var-resolution.spec.md#env_var_resolution-req-0002) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0002 — First-found resolution + + Scenario: ENV_VAR_RESOLUTION-ACC-0010 — Empty first-found value is selected + Given a declaration imports "PRIMARY" before "SECONDARY" + And "PRIMARY" has the collected value "" + And "SECONDARY" has the collected value "fallback-value" + When the software resolves the declaration + Then the declaration resolves to "" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0011 + +Name: Provided canonical value precedes fallback + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env_var_resolution-req-0005) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0005 — Source precedence and absence + + Scenario: ENV_VAR_RESOLUTION-ACC-0011 — Provided canonical value precedes fallback + Given a provided declaration has no import aliases + And its canonical key has the collected value "/custom/tmp" + And its fallback is "/default/tmp" + When the software resolves the declaration + Then the declaration resolves to "/custom/tmp" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0012 + +Name: Provided fallback is used when canonical value is absent + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env_var_resolution-req-0005) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0005 — Source precedence and absence + + Scenario: ENV_VAR_RESOLUTION-ACC-0012 — Provided fallback is used when canonical value is absent + Given a provided declaration has no import aliases + And its canonical key has no collected value + And its fallback is "/default/tmp" + When the software resolves the declaration + Then the declaration resolves to "/default/tmp" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0013 + +Name: Host declaration without aliases ignores its canonical collected value + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env_var_resolution-req-0005) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0005 — Source precedence and absence + + Scenario: ENV_VAR_RESOLUTION-ACC-0013 — Host declaration without aliases ignores its canonical collected value + Given a host declaration has no import aliases + And its canonical key has the collected value "Linux" + And its fallback is "Darwin" + When the software resolves the declaration + Then the declaration resolves to "Darwin" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0014 + +Name: Empty path values are ignored during merge + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env_var_resolution-req-0003) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0003 — Path merge resolution + + Scenario: ENV_VAR_RESOLUTION-ACC-0014 — Empty path values are ignored during merge + Given a merge declaration imports "BIN_A" before "BIN_B" + And "BIN_A" has the collected value "" + And "BIN_B" has the collected value "/usr/bin" + When the software resolves the declaration + Then the declaration resolves to "/usr/bin" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0015 + +Name: Merged paths use the current platform separator + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env_var_resolution-req-0003) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0003 — Path merge resolution + + Scenario: ENV_VAR_RESOLUTION-ACC-0015 — Merged paths use the current platform separator + Given a merge declaration has two non-empty path values + When the software resolves the declaration + Then its paths are joined with the current platform path separator + And duplicate path entries are preserved +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0016 + +Name: Tilde expansion takes precedence and replaces only the first tilde + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + + Scenario: ENV_VAR_RESOLUTION-ACC-0016 — Tilde expansion takes precedence and replaces only the first tilde + Given "HOME" has the collected value "/workspace" + And a declaration fallback is "~/$HOME/~" + When the software resolves the declaration + Then the declaration resolves to "/workspace/$HOME/~" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0017 + +Name: Invalid dollar syntax remains literal + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + + Scenario Outline: ENV_VAR_RESOLUTION-ACC-0017 — Invalid dollar syntax remains literal + Given a declaration fallback is "" + When the software resolves the declaration + Then the declaration resolves to "" + + Examples: + | fallback | + | $ | + | $/cache | + | ${HOME}/cache | +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0018 + +Name: Dollar expansion replaces only the first placeholder + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + + Scenario: ENV_VAR_RESOLUTION-ACC-0018 — Dollar expansion replaces only the first placeholder + Given "HOME" has the collected value "/workspace" + And a declaration fallback is "$HOME/$HOME" + When the software resolves the declaration + Then the declaration resolves to "/workspace/$HOME" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0019 + +Name: Pass-through forwards the first available value + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0006](./env-var-resolution.spec.md#env_var_resolution-req-0006) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0006 — Pass-through resolution + + Scenario: ENV_VAR_RESOLUTION-ACC-0019 — Pass-through forwards the first available value + Given a pass-through declaration imports "SystemRoot" + And "SystemRoot" has the collected value "C:\\Windows" + When the software resolves the declaration + Then the declaration resolves to "C:\\Windows" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0020 + +Name: Pass-through absence resolves to an empty value + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0006](./env-var-resolution.spec.md#env_var_resolution-req-0006) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0006 — Pass-through resolution + + Scenario: ENV_VAR_RESOLUTION-ACC-0020 — Pass-through absence resolves to an empty value + Given a pass-through declaration imports "SystemRoot" + And "SystemRoot" has no collected value + When the software resolves the declaration + Then the declaration resolves to "" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0021 + +Name: Unjoinable merged paths resolve to an empty value + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env_var_resolution-req-0003) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0003 — Path merge resolution + + Scenario: ENV_VAR_RESOLUTION-ACC-0021 — Unjoinable merged paths resolve to an empty value + Given a merge declaration has paths that cannot be joined for the current platform + When the software resolves the declaration + Then the declaration resolves to "" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0022 + +Name: Missing source and fallback resolve to an empty value + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env_var_resolution-req-0005) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0005 — Source precedence and absence + + Scenario: ENV_VAR_RESOLUTION-ACC-0022 — Missing source and fallback resolve to an empty value + Given a host declaration has no import aliases + And the declaration has no fallback + When the software resolves the declaration + Then the declaration resolves to "" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0023 + +Name: Empty provided canonical value precedes fallback + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env_var_resolution-req-0005) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0005 — Source precedence and absence + + Scenario: ENV_VAR_RESOLUTION-ACC-0023 — Empty provided canonical value precedes fallback + Given a provided declaration has no import aliases + And its canonical key has the collected value "" + And its fallback is "/default/tmp" + When the software resolves the declaration + Then the declaration resolves to "" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0024 + +Name: Resolved output preserves declaration and export order + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0007](./env-var-resolution.spec.md#env_var_resolution-req-0007) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0007 — Resolved output order + + Scenario: ENV_VAR_RESOLUTION-ACC-0024 — Resolved output preserves declaration and export order + Given "HOME_TEMP" resolves to "/workspace/.tmp" + And its export aliases are "TEMP", "TMPDIR", and "TMP" in that order + When the software resolves the declaration + Then the resolved keys are "HOME_TEMP", "TEMP", "TMPDIR", and "TMP" in that order + And each resolved key has the value "/workspace/.tmp" +``` + +--- + +## ENV_VAR_RESOLUTION-ACC-0025 + +Name: Collected keys are deduplicated and sorted + +**Links:** + +- [ENV_VAR_RESOLUTION-REQ-0001](./env-var-resolution.spec.md#env_var_resolution-req-0001) + +**Status**: + +- Acceptance status: Draft +- Verification status: Not verified + +```gherkin +Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution + + Rule: ENV_VAR_RESOLUTION-REQ-0001 — Declared import dependency collection + + Scenario: ENV_VAR_RESOLUTION-ACC-0025 — Collected keys are deduplicated and sorted + Given active mappings declare the import aliases "SHELL", "EDITOR", and "SHELL" + When the software collects import dependencies + Then the collected import keys are "EDITOR" and "SHELL" in that order +``` diff --git a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md new file mode 100644 index 0000000..08389d3 --- /dev/null +++ b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md @@ -0,0 +1,224 @@ +--- +title: Environment variables resolution - SPEC +summary: Requirements for resolving declared environment variables. +tags: [environment, env-var, specification, spec, resolution] +status: draft +--- + +> [!IMPORTANT] +> Requirements in this specification use EARS notation. **SHALL** and **SHALL +> NOT** define mandatory behavior; **SHOULD** and **SHOULD NOT** define expected +> behavior that requires an explicit justification to deviate from; **MAY** +> defines optional behavior. +> +> These terms follow RFC 2119 and RFC 8174. + +## Requirements + +### ENV_VAR_RESOLUTION-REQ-0001 + +Name: Declared import dependency collection + +**Links:** + +- [ENV_VAR_RESOLUTION-ACC-0001](./env-var-resolution.acceptance.md#env_var_resolution-acc-0001) +- [ENV_VAR_RESOLUTION-ACC-0002](./env-var-resolution.acceptance.md#env_var_resolution-acc-0002) +- [ENV_VAR_RESOLUTION-ACC-0025](./env-var-resolution.acceptance.md#env_var_resolution-acc-0025) + +**Status**: + +- Requirement status: Draft +- Implementation status: Implemented +- Verification status: Not verified + +**SHALL:** The software collects only import aliases and the first valid dollar +variable reference in a declaration fallback. + +**SHALL:** The software deduplicates and lexicographically sorts collected +import and export keys. + +--- + +### ENV_VAR_RESOLUTION-REQ-0002 + +Name: First-found resolution + +**Links:** + +- [ENV_VAR_RESOLUTION-ACC-0003](./env-var-resolution.acceptance.md#env_var_resolution-acc-0003) +- [ENV_VAR_RESOLUTION-ACC-0004](./env-var-resolution.acceptance.md#env_var_resolution-acc-0004) +- [ENV_VAR_RESOLUTION-ACC-0010](./env-var-resolution.acceptance.md#env_var_resolution-acc-0010) + +**Status**: + +- Requirement status: Draft +- Implementation status: Implemented +- Verification status: Not verified + +**SHALL:** A declaration using first-found import mode resolves the first +available import alias in declaration order. A collected value is available +when it is present, including when its value is empty. + +**WHEN:** No import alias provides a value, + +**THE SOFTWARE SHALL:** resolve the declaration fallback. + +--- + +### ENV_VAR_RESOLUTION-REQ-0003 + +Name: Path merge resolution + +**Links:** + +- [ENV_VAR_RESOLUTION-ACC-0005](./env-var-resolution.acceptance.md#env_var_resolution-acc-0005) +- [ENV_VAR_RESOLUTION-ACC-0006](./env-var-resolution.acceptance.md#env_var_resolution-acc-0006) +- [ENV_VAR_RESOLUTION-ACC-0014](./env-var-resolution.acceptance.md#env_var_resolution-acc-0014) +- [ENV_VAR_RESOLUTION-ACC-0015](./env-var-resolution.acceptance.md#env_var_resolution-acc-0015) +- [ENV_VAR_RESOLUTION-ACC-0021](./env-var-resolution.acceptance.md#env_var_resolution-acc-0021) + +**Status**: + +- Requirement status: Draft +- Implementation status: Implemented +- Verification status: Not verified + +**SHALL:** A declaration using merge import mode ignores empty imported values, +splits each remaining value into paths using the current platform semantics, +and joins the resulting paths in declaration order using the current platform +path separator. + +**SHALL NOT:** Merge resolution deduplicates path entries. + +**WHEN:** No import alias provides a non-empty path value, + +**THE SOFTWARE SHALL:** resolve the declaration fallback. + +**WHEN:** Joining the collected paths cannot produce a valid string for the +current platform, + +**THE SOFTWARE SHALL:** resolve the declaration to an empty string. + +--- + +### ENV_VAR_RESOLUTION-REQ-0004 + +Name: Placeholder expansion + +**Links:** + +- [ENV_VAR_RESOLUTION-ACC-0007](./env-var-resolution.acceptance.md#env_var_resolution-acc-0007) +- [ENV_VAR_RESOLUTION-ACC-0008](./env-var-resolution.acceptance.md#env_var_resolution-acc-0008) +- [ENV_VAR_RESOLUTION-ACC-0009](./env-var-resolution.acceptance.md#env_var_resolution-acc-0009) +- [ENV_VAR_RESOLUTION-ACC-0016](./env-var-resolution.acceptance.md#env_var_resolution-acc-0016) +- [ENV_VAR_RESOLUTION-ACC-0017](./env-var-resolution.acceptance.md#env_var_resolution-acc-0017) +- [ENV_VAR_RESOLUTION-ACC-0018](./env-var-resolution.acceptance.md#env_var_resolution-acc-0018) + +**Status**: + +- Requirement status: Draft +- Implementation status: Implemented +- Verification status: Not verified + +**SHALL:** When a fallback contains a tilde and a non-empty collected `HOME` +value is available, the software replaces the first tilde with that value. + +**SHALL:** When a non-empty collected `HOME` value is available, tilde +expansion takes precedence over dollar expansion. + +**WHEN:** A fallback contains a tilde but no non-empty collected `HOME` value +is available, + +**THE SOFTWARE SHALL:** leave the tilde unchanged and evaluate a dollar +placeholder when one is present. + +**SHALL:** A dollar placeholder is the first dollar sign followed by one or +more ASCII letters, digits, or underscores. The software replaces the first +occurrence of that placeholder with the collected value whose key matches its +name, including an empty value. + +**WHEN:** A dollar sign has no valid placeholder name or a dollar placeholder +has no collected value, + +**THE SOFTWARE SHALL:** preserve it literally. + +--- + +### ENV_VAR_RESOLUTION-REQ-0005 + +Name: Source precedence and absence + +**Links:** + +- [ENV_VAR_RESOLUTION-ACC-0011](./env-var-resolution.acceptance.md#env_var_resolution-acc-0011) +- [ENV_VAR_RESOLUTION-ACC-0012](./env-var-resolution.acceptance.md#env_var_resolution-acc-0012) +- [ENV_VAR_RESOLUTION-ACC-0013](./env-var-resolution.acceptance.md#env_var_resolution-acc-0013) +- [ENV_VAR_RESOLUTION-ACC-0022](./env-var-resolution.acceptance.md#env_var_resolution-acc-0022) +- [ENV_VAR_RESOLUTION-ACC-0023](./env-var-resolution.acceptance.md#env_var_resolution-acc-0023) + +**Status**: + +- Requirement status: Draft +- Implementation status: Implemented +- Verification status: Not verified + +**SHALL:** A declaration without import aliases and with source `Provided` +uses its collected canonical value when it is present, including when the value +is empty. + +**WHEN:** That provided canonical value is absent, + +**THE SOFTWARE SHALL:** resolve the declaration fallback. + +**SHALL:** A declaration without import aliases and with source `Host` resolves +its fallback without reading a collected value for its canonical key. + +**WHEN:** The selected source and fallback provide no value, + +**THE SOFTWARE SHALL:** resolve the declaration to an empty string. + +--- + +### ENV_VAR_RESOLUTION-REQ-0006 + +Name: Pass-through resolution + +**Links:** + +- [ENV_VAR_RESOLUTION-ACC-0019](./env-var-resolution.acceptance.md#env_var_resolution-acc-0019) +- [ENV_VAR_RESOLUTION-ACC-0020](./env-var-resolution.acceptance.md#env_var_resolution-acc-0020) + +**Status**: + +- Requirement status: Draft +- Implementation status: Implemented +- Verification status: Not verified + +**SHALL:** A declaration using pass-through import mode resolves the first +available import alias in declaration order without applying a fallback. + +**WHEN:** No import alias provides a value, + +**THE SOFTWARE SHALL:** resolve the declaration to an empty string. + +--- + +### ENV_VAR_RESOLUTION-REQ-0007 + +Name: Resolved output order + +**Links:** + +- [ENV_VAR_RESOLUTION-ACC-0024](./env-var-resolution.acceptance.md#env_var_resolution-acc-0024) + +**Status**: + +- Requirement status: Draft +- Implementation status: Implemented +- Verification status: Not verified + +**SHALL:** The software emits resolved declarations in active mapping order. + +**SHALL:** For each declaration, the software emits the canonical key first, +followed by its export aliases in declaration order. Every emitted key has the +same resolved value. From 8900576c5c6ae29727b4377196b06940e51d8635 Mon Sep 17 00:00:00 2001 From: "Alex G. Wolff" <13754094+alexgwolff@users.noreply.github.com> Date: Tue, 22 Sep 2026 11:15:38 -0300 Subject: [PATCH 02/15] fix env names Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com> --- .../env-var-declarations.acceptance.md | 12 ++++++------ .../env-var-projection.acceptance.md | 14 +++++++------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md index a27df15..e332e9c 100644 --- a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md +++ b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md @@ -19,10 +19,10 @@ Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations Rule: ENV_VAR_DECLARATIONS-REQ-0001 — Static declaration Scenario: ENV_VAR_DECLARATIONS-ACC-0001 — Unknown runtime declaration is rejected - Given no declaration exists for "EXAMPLE_TOKEN" - When runtime configuration provides a value for "EXAMPLE_TOKEN" + Given no declaration exists for "ENV_VAR_X" + When runtime configuration provides a value for "ENV_VAR_X" Then the software rejects the configuration - And "EXAMPLE_TOKEN" is not projected to a managed process + And "ENV_VAR_X" is not projected to a managed process ``` --- @@ -46,8 +46,8 @@ Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations Rule: ENV_VAR_DECLARATIONS-REQ-0001 — Static declaration Scenario: ENV_VAR_DECLARATIONS-ACC-0002 — Known runtime declaration accepts a value - Given a declaration exists for "EXAMPLE_TOKEN" - When runtime configuration provides a value for "EXAMPLE_TOKEN" + Given a declaration exists for "ENV_VAR_X" + When runtime configuration provides a value for "ENV_VAR_X" Then the software accepts the configuration ``` @@ -72,7 +72,7 @@ Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations Rule: ENV_VAR_DECLARATIONS-REQ-0002 — Canonical key uniqueness Scenario: ENV_VAR_DECLARATIONS-ACC-0003 — Duplicate canonical key is rejected - Given two declarations use the canonical key "EXAMPLE_TOKEN" + Given two declarations use the canonical key "ENV_VAR_X" When the software loads the declaration set Then the software rejects the declaration set ``` diff --git a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md index 9f7a250..3896e0a 100644 --- a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md +++ b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md @@ -24,10 +24,10 @@ Feature: ENV_VAR_PROJECTION-FEAT-0001 — Environment variable projection Rule: ENV_VAR_PROJECTION-REQ-0001 — Explicit export authorization Scenario: ENV_VAR_PROJECTION-ACC-0001 — Declared export alias is projected - Given "EXAMPLE_TOKEN" is declared as an export alias - And "EXAMPLE_TOKEN" has a resolved value + Given "ENV_VAR_X" is declared as an export alias + And "ENV_VAR_X" has a resolved value When the software applies the projection to a managed process - Then the managed process receives "EXAMPLE_TOKEN" + Then the managed process receives "ENV_VAR_X" ``` --- @@ -48,13 +48,13 @@ Name: Non-exportable resolved value is not projected ```gherkin Feature: ENV_VAR_PROJECTION-FEAT-0001 — Environment variable projection - Rule: ENV_VAR_PROJECTION-REQ-0001 — Explicit export authorization + Rule: ENV_VAR_PROJECTION-REQ-0001 — Explicit export Scenario: ENV_VAR_PROJECTION-ACC-0002 — Non-exportable resolved value is not projected - Given "INTERNAL_TOKEN" has a resolved value - And "INTERNAL_TOKEN" is not declared as an export alias + Given "ENV_VAR_X" has a resolved value + And "ENV_VAR_X" is not declared as an export alias When the software applies the projection to a managed process - Then the managed process does not receive "INTERNAL_TOKEN" + Then the managed process does not receive "ENV_VAR_X" ``` --- From c253433fcfc3e68be163622dc73db959455857f8 Mon Sep 17 00:00:00 2001 From: "Alex G. Wolff" <13754094+alexgwolff@users.noreply.github.com> Date: Tue, 22 Sep 2026 19:53:21 -0300 Subject: [PATCH 03/15] temp Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com> --- SPECIFICATIONS.md | 172 ---------------------------------------------- 1 file changed, 172 deletions(-) delete mode 100644 SPECIFICATIONS.md diff --git a/SPECIFICATIONS.md b/SPECIFICATIONS.md deleted file mode 100644 index f336bf6..0000000 --- a/SPECIFICATIONS.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Specifications -summary: Conventions for documenting feature intent, requirements, and acceptance scenarios. -tags: [specification, requirements, acceptance, ears, documentation] ---- - -## Purpose - -This document defines how Kraf records feature intent, behavioral requirements, -and acceptance scenarios. - -It defines the documentation protocol, not the behavior of a specific feature. - -## Document types - -### Intent - -An intent explains why a feature exists, the problem it addresses, its -boundaries, and its non-goals. It is not normative. - -### Specification - -A specification defines normative, traceable behavioral requirements. Each -requirement has a stable identifier, a name, statuses, and links to its -acceptance scenarios. - -### Acceptance - -An acceptance document defines observable scenarios derived from requirements. -Scenarios use embedded Gherkin and link back to the requirement they verify. - -## Traceability - -```text -Intent → Requirement ↔ Acceptance -``` - -A requirement may have multiple acceptance scenarios. An acceptance scenario -belongs to one primary requirement. - -## Feature-local layout - -Documentation lives with the feature it describes. - -```text -/ -└── docs/ - ├── -intent.md - └── / - ├── .spec.md - └── .acceptance.md -``` - -Documentation does not need to map one-to-one to source files, platform files, -or tests. Create a document when a domain behavior needs a durable contract. - -## Identifiers - -Identifiers use an uppercase feature area, followed by a type and a four-digit -sequence number. - -```text -_-FEAT-0001 -_-REQ-0001 -_-ACC-0001 -``` - -For example: - -```text -ENV_VAR_DECLARATIONS-REQ-0001 -ENV_VAR_DECLARATIONS-ACC-0001 -``` - -## Normative language - -Specifications use EARS notation and the normative terms defined by RFC 2119 -and RFC 8174. - -- **SHALL** and **SHALL NOT** define mandatory behavior. -- **SHOULD** and **SHOULD NOT** define expected behavior that requires an - explicit justification to deviate from. -- **MAY** defines optional behavior. - -Use the EARS pattern that matches the behavior: - -```text -The software SHALL . - -WHEN , -THE SOFTWARE SHALL . - -IF , -THEN THE SOFTWARE SHALL . -``` - -## Statuses - -Each requirement declares three independent statuses: - -- **Requirement status:** `Draft`, `Accepted`, or `Superseded`. -- **Implementation status:** `Not implemented`, `Partially implemented`, or - `Implemented`. -- **Verification status:** `Not verified` or `Verified`. - -Each acceptance scenario declares its own acceptance and verification status. -Implementation status belongs to the requirement, not to each scenario. - -## Minimal example - -An intent establishes the boundary: - -```md -## Intent - -The feature must make process configuration explicit rather than inheriting -undeclared host state. -``` - -A specification defines a requirement and links to acceptance evidence: - -```md -### EXAMPLE_AREA-REQ-0001 - -Name: Explicit configuration - -**Links:** - -- [EXAMPLE_AREA-ACC-0001](./example.acceptance.md#example_area-acc-0001) - -**Status**: - -- Requirement status: Draft -- Implementation status: Not implemented -- Verification status: Not verified - -**WHEN:** Configuration provides an unknown key, - -**THE SOFTWARE SHALL:** reject the configuration. -``` - -Acceptance links back and states the observable behavior: - -````md -## EXAMPLE_AREA-ACC-0001 - -Name: Unknown configuration key is rejected - -**Links:** - -- [EXAMPLE_AREA-REQ-0001](./example.spec.md#example_area-req-0001) - -```gherkin -Feature: EXAMPLE_AREA-FEAT-0001 — Explicit configuration - - Rule: EXAMPLE_AREA-REQ-0001 — Explicit configuration - - Scenario: EXAMPLE_AREA-ACC-0001 — Unknown configuration key is rejected - Given no declaration exists for "EXAMPLE_KEY" - When configuration provides a value for "EXAMPLE_KEY" - Then the software rejects the configuration -``` -```` - -## Current reference - -The environment-variable feature is the current reference implementation of -this convention: - -- [Environment variable intent](./src/environment/src/env_var/docs/env-var-intent.md) -- [Environment variable declarations specification](./src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md) -- [Environment variable declarations acceptance](./src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md) From d891c9da307ad8785dcb67f6fb550c520bf3a7d5 Mon Sep 17 00:00:00 2001 From: "Alex G. Wolff" <13754094+alexgwolff@users.noreply.github.com> Date: Tue, 22 Sep 2026 20:37:54 -0300 Subject: [PATCH 04/15] rewrite docs with new pattern Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com> --- .../env-var-declarations.acceptance.md | 102 ++--- .../env-var-declarations.spec.md | 34 +- .../env-var-host/env-var-host.acceptance.md | 57 ++- .../docs/env-var-host/env-var-host.spec.md | 23 +- .../src/env_var/docs/env-var-intent.md | 12 + .../env-var-projection.acceptance.md | 55 ++- .../env-var-projection.spec.md | 21 +- .../env-var-resolution.acceptance.md | 351 +++++++++--------- .../env-var-resolution.spec.md | 128 ++++--- 9 files changed, 403 insertions(+), 380 deletions(-) diff --git a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md index e332e9c..25ca690 100644 --- a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md +++ b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md @@ -1,103 +1,107 @@ -# Environment variables declaration — Acceptance +--- +title: Environment variables declaration - Acceptance +summary: Acceptance scenarios for declaring environment variables. +tags: [environment, env-var, acceptance, declaration, gherkin] +--- -## ENV_VAR_DECLARATIONS-ACC-0001 +## ENV-VAR_DECLARATIONS-ACC-0001 Name: Unknown runtime declaration is rejected **Links:** -- [ENV_VAR_DECLARATIONS-REQ-0001](./env-var-declarations.spec.md#env_var_declarations-req-0001) +- [ENV-VAR_DECLARATIONS-REQ-0001](./env-var-declarations.spec.md#env-var_declarations-req-0001) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations +Feature: ENV-VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations - Rule: ENV_VAR_DECLARATIONS-REQ-0001 — Static declaration + Rule: ENV-VAR_DECLARATIONS-REQ-0001 — Static declaration - Scenario: ENV_VAR_DECLARATIONS-ACC-0001 — Unknown runtime declaration is rejected - Given no declaration exists for "ENV_VAR_X" - When runtime configuration provides a value for "ENV_VAR_X" + Scenario: ENV-VAR_DECLARATIONS-ACC-0001 — Unknown runtime declaration is rejected + Given no declaration exists for "ENV-VAR_X" + When runtime configuration provides a value for "ENV-VAR_X" Then the software rejects the configuration - And "ENV_VAR_X" is not projected to a managed process + And "ENV-VAR_X" is not projected to a managed process ``` --- -## ENV_VAR_DECLARATIONS-ACC-0002 +## ENV-VAR_DECLARATIONS-ACC-0002 Name: Known runtime declaration accepts a value **Links:** -- [ENV_VAR_DECLARATIONS-REQ-0001](./env-var-declarations.spec.md#env_var_declarations-req-0001) +- [ENV-VAR_DECLARATIONS-REQ-0001](./env-var-declarations.spec.md#env-var_declarations-req-0001) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations +Feature: ENV-VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations - Rule: ENV_VAR_DECLARATIONS-REQ-0001 — Static declaration + Rule: ENV-VAR_DECLARATIONS-REQ-0001 — Static declaration - Scenario: ENV_VAR_DECLARATIONS-ACC-0002 — Known runtime declaration accepts a value - Given a declaration exists for "ENV_VAR_X" - When runtime configuration provides a value for "ENV_VAR_X" + Scenario: ENV-VAR_DECLARATIONS-ACC-0002 — Known runtime declaration accepts a value + Given a declaration exists for "ENV-VAR_X" + When runtime configuration provides a value for "ENV-VAR_X" Then the software accepts the configuration ``` --- -## ENV_VAR_DECLARATIONS-ACC-0003 +## ENV-VAR_DECLARATIONS-ACC-0003 Name: Duplicate canonical key is rejected **Links:** -- [ENV_VAR_DECLARATIONS-REQ-0002](./env-var-declarations.spec.md#env_var_declarations-req-0002) +- [ENV-VAR_DECLARATIONS-REQ-0002](./env-var-declarations.spec.md#env-var_declarations-req-0002) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations +Feature: ENV-VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations - Rule: ENV_VAR_DECLARATIONS-REQ-0002 — Canonical key uniqueness + Rule: ENV-VAR_DECLARATIONS-REQ-0002 — Canonical key uniqueness - Scenario: ENV_VAR_DECLARATIONS-ACC-0003 — Duplicate canonical key is rejected - Given two declarations use the canonical key "ENV_VAR_X" + Scenario: ENV-VAR_DECLARATIONS-ACC-0003 — Duplicate canonical key is rejected + Given two declarations use the canonical key "ENV-VAR_X" When the software loads the declaration set Then the software rejects the declaration set ``` --- -## ENV_VAR_DECLARATIONS-ACC-0004 +## ENV-VAR_DECLARATIONS-ACC-0004 Name: Merge mapping declares multiple import aliases **Links:** -- [ENV_VAR_DECLARATIONS-REQ-0003](./env-var-declarations.spec.md#env_var_declarations-req-0003) +- [ENV-VAR_DECLARATIONS-REQ-0003](./env-var-declarations.spec.md#env-var_declarations-req-0003) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations +Feature: ENV-VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations - Rule: ENV_VAR_DECLARATIONS-REQ-0003 — Mapping mode validity + Rule: ENV-VAR_DECLARATIONS-REQ-0003 — Mapping mode validity - Scenario: ENV_VAR_DECLARATIONS-ACC-0004 — Merge mapping declares multiple import aliases + Scenario: ENV-VAR_DECLARATIONS-ACC-0004 — Merge mapping declares multiple import aliases Given a declaration uses merge import mode When the declaration defines fewer than two import aliases Then the software rejects the declaration @@ -105,25 +109,25 @@ Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations --- -## ENV_VAR_DECLARATIONS-ACC-0005 +## ENV-VAR_DECLARATIONS-ACC-0005 Name: Pass-through mapping imports only its canonical key **Links:** -- [ENV_VAR_DECLARATIONS-REQ-0003](./env-var-declarations.spec.md#env_var_declarations-req-0003) +- [ENV-VAR_DECLARATIONS-REQ-0003](./env-var-declarations.spec.md#env-var_declarations-req-0003) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations +Feature: ENV-VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations - Rule: ENV_VAR_DECLARATIONS-REQ-0003 — Mapping mode validity + Rule: ENV-VAR_DECLARATIONS-REQ-0003 — Mapping mode validity - Scenario: ENV_VAR_DECLARATIONS-ACC-0005 — Pass-through mapping imports only its canonical key + Scenario: ENV-VAR_DECLARATIONS-ACC-0005 — Pass-through mapping imports only its canonical key Given a declaration uses pass-through import mode When the declaration imports an alias other than its canonical key Then the software rejects the declaration @@ -131,25 +135,25 @@ Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations --- -## ENV_VAR_DECLARATIONS-ACC-0006 +## ENV-VAR_DECLARATIONS-ACC-0006 Name: Pass-through mapping has no fallback **Links:** -- [ENV_VAR_DECLARATIONS-REQ-0003](./env-var-declarations.spec.md#env_var_declarations-req-0003) +- [ENV-VAR_DECLARATIONS-REQ-0003](./env-var-declarations.spec.md#env-var_declarations-req-0003) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations +Feature: ENV-VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations - Rule: ENV_VAR_DECLARATIONS-REQ-0003 — Mapping mode validity + Rule: ENV-VAR_DECLARATIONS-REQ-0003 — Mapping mode validity - Scenario: ENV_VAR_DECLARATIONS-ACC-0006 — Pass-through mapping has no fallback + Scenario: ENV-VAR_DECLARATIONS-ACC-0006 — Pass-through mapping has no fallback Given a declaration uses pass-through import mode When the declaration defines a fallback Then the software rejects the declaration diff --git a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md index 4d8af85..11c63ef 100644 --- a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md +++ b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md @@ -2,7 +2,6 @@ title: Environment variables declaration - SPEC summary: Requirements for declaring environment variables. tags: [environment, env-var, specification, spec, declaration] -status: draft --- > [!IMPORTANT] @@ -15,20 +14,21 @@ status: draft ## Requirements -### ENV_VAR_DECLARATIONS-REQ-0001 +### ENV-VAR_DECLARATIONS-REQ-0001 Name: Static declaration **Links:** -- [ENV_VAR_DECLARATIONS-ACC-0001](./env-var-declarations.acceptance.md#env_var_declarations-acc-0001) -- [ENV_VAR_DECLARATIONS-ACC-0002](./env-var-declarations.acceptance.md#env_var_declarations-acc-0002) +- [ENV-VAR_DECLARATIONS-ACC-0001](./env-var-declarations.acceptance.md#env-var_declarations-acc-0001) +- [ENV-VAR_DECLARATIONS-ACC-0002](./env-var-declarations.acceptance.md#env-var_declarations-acc-0002) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Not implemented -- Verification status: Not verified **SHALL:** The software resolves and projects only environment-variable declarations that are built into the software or packaged as immutable metadata @@ -45,19 +45,20 @@ aliases, export aliases, or source eligibility. --- -### ENV_VAR_DECLARATIONS-REQ-0002 +### ENV-VAR_DECLARATIONS-REQ-0002 Name: Canonical key uniqueness **Links:** -- [ENV_VAR_DECLARATIONS-ACC-0003](./env-var-declarations.acceptance.md#env_var_declarations-acc-0003) +- [ENV-VAR_DECLARATIONS-ACC-0003](./env-var-declarations.acceptance.md#env-var_declarations-acc-0003) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Partially implemented -- Verification status: Not verified **SHALL:** The software accepts at most one declaration for each canonical key. @@ -67,21 +68,22 @@ Name: Canonical key uniqueness --- -### ENV_VAR_DECLARATIONS-REQ-0003 +### ENV-VAR_DECLARATIONS-REQ-0003 Name: Mapping mode validity **Links:** -- [ENV_VAR_DECLARATIONS-ACC-0004](./env-var-declarations.acceptance.md#env_var_declarations-acc-0004) -- [ENV_VAR_DECLARATIONS-ACC-0005](./env-var-declarations.acceptance.md#env_var_declarations-acc-0005) -- [ENV_VAR_DECLARATIONS-ACC-0006](./env-var-declarations.acceptance.md#env_var_declarations-acc-0006) +- [ENV-VAR_DECLARATIONS-ACC-0004](./env-var-declarations.acceptance.md#env-var_declarations-acc-0004) +- [ENV-VAR_DECLARATIONS-ACC-0005](./env-var-declarations.acceptance.md#env-var_declarations-acc-0005) +- [ENV-VAR_DECLARATIONS-ACC-0006](./env-var-declarations.acceptance.md#env-var_declarations-acc-0006) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Partially implemented -- Verification status: Not verified **SHALL:** A declaration using merge import mode declares at least two import aliases. diff --git a/src/environment/src/env_var/docs/env-var-host/env-var-host.acceptance.md b/src/environment/src/env_var/docs/env-var-host/env-var-host.acceptance.md index 6e9d558..5e0d886 100644 --- a/src/environment/src/env_var/docs/env-var-host/env-var-host.acceptance.md +++ b/src/environment/src/env_var/docs/env-var-host/env-var-host.acceptance.md @@ -2,28 +2,27 @@ title: Environment variables host mappings - Acceptance summary: Acceptance scenarios for platform-specific environment-variable mappings. tags: [environment, env-var, acceptance, host, platform, gherkin] -status: draft --- -## ENV_VAR_HOST-ACC-0001 +## ENV-VAR_HOST-ACC-0001 Name: Every shared canonical key has a Linux mapping **Links:** -- [ENV_VAR_HOST-REQ-0001](./env-var-host.spec.md#env_var_host-req-0001) +- [ENV-VAR_HOST-REQ-0001](./env-var-host.spec.md#env-var_host-req-0001) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_HOST-FEAT-0001 — Environment variable host mappings +Feature: ENV-VAR_HOST-FEAT-0001 — Environment variable host mappings - Rule: ENV_VAR_HOST-REQ-0001 — Supported-platform mapping completeness + Rule: ENV-VAR_HOST-REQ-0001 — Supported-platform mapping completeness - Scenario: ENV_VAR_HOST-ACC-0001 — Every shared canonical key has a Linux mapping + Scenario: ENV-VAR_HOST-ACC-0001 — Every shared canonical key has a Linux mapping Given the shared canonical environment-variable keys When the Linux mappings are loaded Then every shared canonical key has a Linux mapping @@ -31,25 +30,25 @@ Feature: ENV_VAR_HOST-FEAT-0001 — Environment variable host mappings --- -## ENV_VAR_HOST-ACC-0002 +## ENV-VAR_HOST-ACC-0002 Name: Every shared canonical key has a macOS mapping **Links:** -- [ENV_VAR_HOST-REQ-0001](./env-var-host.spec.md#env_var_host-req-0001) +- [ENV-VAR_HOST-REQ-0001](./env-var-host.spec.md#env-var_host-req-0001) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_HOST-FEAT-0001 — Environment variable host mappings +Feature: ENV-VAR_HOST-FEAT-0001 — Environment variable host mappings - Rule: ENV_VAR_HOST-REQ-0001 — Supported-platform mapping completeness + Rule: ENV-VAR_HOST-REQ-0001 — Supported-platform mapping completeness - Scenario: ENV_VAR_HOST-ACC-0002 — Every shared canonical key has a macOS mapping + Scenario: ENV-VAR_HOST-ACC-0002 — Every shared canonical key has a macOS mapping Given the shared canonical environment-variable keys When the macOS mappings are loaded Then every shared canonical key has a macOS mapping @@ -57,25 +56,25 @@ Feature: ENV_VAR_HOST-FEAT-0001 — Environment variable host mappings --- -## ENV_VAR_HOST-ACC-0003 +## ENV-VAR_HOST-ACC-0003 Name: Every shared canonical key has a Windows mapping **Links:** -- [ENV_VAR_HOST-REQ-0001](./env-var-host.spec.md#env_var_host-req-0001) +- [ENV-VAR_HOST-REQ-0001](./env-var-host.spec.md#env-var_host-req-0001) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_HOST-FEAT-0001 — Environment variable host mappings +Feature: ENV-VAR_HOST-FEAT-0001 — Environment variable host mappings - Rule: ENV_VAR_HOST-REQ-0001 — Supported-platform mapping completeness + Rule: ENV-VAR_HOST-REQ-0001 — Supported-platform mapping completeness - Scenario: ENV_VAR_HOST-ACC-0003 — Every shared canonical key has a Windows mapping + Scenario: ENV-VAR_HOST-ACC-0003 — Every shared canonical key has a Windows mapping Given the shared canonical environment-variable keys When the Windows mappings are loaded Then every shared canonical key has a Windows mapping @@ -83,25 +82,25 @@ Feature: ENV_VAR_HOST-FEAT-0001 — Environment variable host mappings --- -## ENV_VAR_HOST-ACC-0004 +## ENV-VAR_HOST-ACC-0004 Name: Home and work-directory declarations use provided values **Links:** -- [ENV_VAR_HOST-REQ-0002](./env-var-host.spec.md#env_var_host-req-0002) +- [ENV-VAR_HOST-REQ-0002](./env-var-host.spec.md#env-var_host-req-0002) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_HOST-FEAT-0001 — Environment variable host mappings +Feature: ENV-VAR_HOST-FEAT-0001 — Environment variable host mappings - Rule: ENV_VAR_HOST-REQ-0002 — Session-owned directory sources + Rule: ENV-VAR_HOST-REQ-0002 — Session-owned directory sources - Scenario: ENV_VAR_HOST-ACC-0004 — Home and work-directory declarations use provided values + Scenario: ENV-VAR_HOST-ACC-0004 — Home and work-directory declarations use provided values Given a supported platform mapping When the mapping declares WORKDIR or a HOME family key Then the declaration source is provided diff --git a/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md b/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md index 4c4b7a0..d2fa40c 100644 --- a/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md +++ b/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md @@ -2,7 +2,6 @@ title: Environment variables host mappings - SPEC summary: Requirements for platform-specific environment-variable mappings. tags: [environment, env-var, specification, spec, host, platform] -status: draft --- > [!IMPORTANT] @@ -15,40 +14,42 @@ status: draft ## Requirements -### ENV_VAR_HOST-REQ-0001 +### ENV-VAR_HOST-REQ-0001 Name: Supported-platform mapping completeness **Links:** -- [ENV_VAR_HOST-ACC-0001](./env-var-host.acceptance.md#env_var_host-acc-0001) -- [ENV_VAR_HOST-ACC-0002](./env-var-host.acceptance.md#env_var_host-acc-0002) -- [ENV_VAR_HOST-ACC-0003](./env-var-host.acceptance.md#env_var_host-acc-0003) +- [ENV-VAR_HOST-ACC-0001](./env-var-host.acceptance.md#env-var_host-acc-0001) +- [ENV-VAR_HOST-ACC-0002](./env-var-host.acceptance.md#env-var_host-acc-0002) +- [ENV-VAR_HOST-ACC-0003](./env-var-host.acceptance.md#env-var_host-acc-0003) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Implemented -- Verification status: Not verified **SHALL:** Every supported platform mapping declares every shared canonical environment-variable key. --- -### ENV_VAR_HOST-REQ-0002 +### ENV-VAR_HOST-REQ-0002 Name: Session-owned directory sources **Links:** -- [ENV_VAR_HOST-ACC-0004](./env-var-host.acceptance.md#env_var_host-acc-0004) +- [ENV-VAR_HOST-ACC-0004](./env-var-host.acceptance.md#env-var_host-acc-0004) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Implemented -- Verification status: Not verified **SHALL:** The WORKDIR and HOME declaration families use provided values rather than values imported from the host. diff --git a/src/environment/src/env_var/docs/env-var-intent.md b/src/environment/src/env_var/docs/env-var-intent.md index 2aeb06c..22eb5dc 100644 --- a/src/environment/src/env_var/docs/env-var-intent.md +++ b/src/environment/src/env_var/docs/env-var-intent.md @@ -77,3 +77,15 @@ It does not: Session creation and process launch belong to the trap module. The trap provides session-owned values, requests a resolved projection, and applies that projection to its managed process. + +## Documentation + +- [Readme](../README.md): module overview. +- [Declarations](./env-var-declarations/env-var-declarations.spec.md): + declarations Specification. +- [Resolution](./env-var-resolution/env-var-resolution.spec.md): + resolution Specification. +- [Projection](./env-var-projection/env-var-projection.spec.md): + projection Specification. +- [Host mappings](./env-var-host/env-var-host.spec.md): + host mappings Specification. diff --git a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md index 3896e0a..3b154ed 100644 --- a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md +++ b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md @@ -2,82 +2,81 @@ title: Environment variables projection - Acceptance summary: Acceptance scenarios for projecting environment variables. tags: [environment, env-var, acceptance, projection, gherkin] -status: draft --- -## ENV_VAR_PROJECTION-ACC-0001 +## ENV-VAR_PROJECTION-ACC-0001 Name: Declared export alias is projected **Links:** -- [ENV_VAR_PROJECTION-REQ-0001](./env-var-projection.spec.md#env_var_projection-req-0001) +- [ENV-VAR_PROJECTION-REQ-0001](./env-var-projection.spec.md#env-var_projection-req-0001) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_PROJECTION-FEAT-0001 — Environment variable projection +Feature: ENV-VAR_PROJECTION-FEAT-0001 — Environment variable projection - Rule: ENV_VAR_PROJECTION-REQ-0001 — Explicit export authorization + Rule: ENV-VAR_PROJECTION-REQ-0001 — Explicit export authorization - Scenario: ENV_VAR_PROJECTION-ACC-0001 — Declared export alias is projected - Given "ENV_VAR_X" is declared as an export alias - And "ENV_VAR_X" has a resolved value + Scenario: ENV-VAR_PROJECTION-ACC-0001 — Declared export alias is projected + Given "ENV-VAR_X" is declared as an export alias + And "ENV-VAR_X" has a resolved value When the software applies the projection to a managed process - Then the managed process receives "ENV_VAR_X" + Then the managed process receives "ENV-VAR_X" ``` --- -## ENV_VAR_PROJECTION-ACC-0002 +## ENV-VAR_PROJECTION-ACC-0002 Name: Non-exportable resolved value is not projected **Links:** -- [ENV_VAR_PROJECTION-REQ-0001](./env-var-projection.spec.md#env_var_projection-req-0001) +- [ENV-VAR_PROJECTION-REQ-0001](./env-var-projection.spec.md#env-var_projection-req-0001) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_PROJECTION-FEAT-0001 — Environment variable projection +Feature: ENV-VAR_PROJECTION-FEAT-0001 — Environment variable projection - Rule: ENV_VAR_PROJECTION-REQ-0001 — Explicit export + Rule: ENV-VAR_PROJECTION-REQ-0001 — Explicit export authorization - Scenario: ENV_VAR_PROJECTION-ACC-0002 — Non-exportable resolved value is not projected - Given "ENV_VAR_X" has a resolved value - And "ENV_VAR_X" is not declared as an export alias + Scenario: ENV-VAR_PROJECTION-ACC-0002 — Non-exportable resolved value is not projected + Given "ENV-VAR_X" has a resolved value + And "ENV-VAR_X" is not declared as an export alias When the software applies the projection to a managed process - Then the managed process does not receive "ENV_VAR_X" + Then the managed process does not receive "ENV-VAR_X" ``` --- -## ENV_VAR_PROJECTION-ACC-0003 +## ENV-VAR_PROJECTION-ACC-0003 Name: Export aliases receive the canonical resolved value **Links:** -- [ENV_VAR_PROJECTION-REQ-0002](./env-var-projection.spec.md#env_var_projection-req-0002) +- [ENV-VAR_PROJECTION-REQ-0002](./env-var-projection.spec.md#env-var_projection-req-0002) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_PROJECTION-FEAT-0001 — Environment variable projection +Feature: ENV-VAR_PROJECTION-FEAT-0001 — Environment variable projection - Rule: ENV_VAR_PROJECTION-REQ-0002 — Export value symmetry + Rule: ENV-VAR_PROJECTION-REQ-0002 — Export value symmetry - Scenario: ENV_VAR_PROJECTION-ACC-0003 — Export aliases receive the canonical resolved value + Scenario: ENV-VAR_PROJECTION-ACC-0003 — Export aliases receive the canonical resolved value Given "HOME_TEMP" resolves to "/workspace/.tmp" And "TMPDIR" is an export alias of "HOME_TEMP" When the software resolves the declaration diff --git a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md index b0168a8..b783967 100644 --- a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md +++ b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md @@ -2,7 +2,6 @@ title: Environment variables projection - SPEC summary: Requirements for projecting resolved environment variables to managed processes. tags: [environment, env-var, specification, spec, projection] -status: draft --- > [!IMPORTANT] @@ -15,39 +14,41 @@ status: draft ## Requirements -### ENV_VAR_PROJECTION-REQ-0001 +### ENV-VAR_PROJECTION-REQ-0001 Name: Explicit export authorization **Links:** -- [ENV_VAR_PROJECTION-ACC-0001](./env-var-projection.acceptance.md#env_var_projection-acc-0001) -- [ENV_VAR_PROJECTION-ACC-0002](./env-var-projection.acceptance.md#env_var_projection-acc-0002) +- [ENV-VAR_PROJECTION-ACC-0001](./env-var-projection.acceptance.md#env-var_projection-acc-0001) +- [ENV-VAR_PROJECTION-ACC-0002](./env-var-projection.acceptance.md#env-var_projection-acc-0002) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Implemented -- Verification status: Not verified **SHALL:** The software projects only keys declared as export aliases by the active mappings. --- -### ENV_VAR_PROJECTION-REQ-0002 +### ENV-VAR_PROJECTION-REQ-0002 Name: Export value symmetry **Links:** -- [ENV_VAR_PROJECTION-ACC-0003](./env-var-projection.acceptance.md#env_var_projection-acc-0003) +- [ENV-VAR_PROJECTION-ACC-0003](./env-var-projection.acceptance.md#env-var_projection-acc-0003) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Implemented -- Verification status: Not verified **SHALL:** Every export alias produced by a declaration has the declaration's resolved value. diff --git a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.acceptance.md b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.acceptance.md index 872dd33..515a17b 100644 --- a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.acceptance.md +++ b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.acceptance.md @@ -2,28 +2,27 @@ title: Environment variables resolution - Acceptance summary: Acceptance scenarios for environment-variable resolution. tags: [environment, env-var, acceptance, resolution, gherkin] -status: draft --- -## ENV_VAR_RESOLUTION-ACC-0001 +## ENV-VAR_RESOLUTION-ACC-0001 Name: Import aliases are collected and deduplicated **Links:** -- [ENV_VAR_RESOLUTION-REQ-0001](./env-var-resolution.spec.md#env_var_resolution-req-0001) +- [ENV-VAR_RESOLUTION-REQ-0001](./env-var-resolution.spec.md#env-var_resolution-req-0001) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0001 — Declared import dependency collection + Rule: ENV-VAR_RESOLUTION-REQ-0001 — Declared import dependency collection - Scenario: ENV_VAR_RESOLUTION-ACC-0001 — Import aliases are collected and deduplicated + Scenario: ENV-VAR_RESOLUTION-ACC-0001 — Import aliases are collected and deduplicated Given multiple declarations import the alias "SHELL" When the software collects import dependencies Then "SHELL" is collected once @@ -31,25 +30,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0002 +## ENV-VAR_RESOLUTION-ACC-0002 Name: Fallback variable reference is collected **Links:** -- [ENV_VAR_RESOLUTION-REQ-0001](./env-var-resolution.spec.md#env_var_resolution-req-0001) +- [ENV-VAR_RESOLUTION-REQ-0001](./env-var-resolution.spec.md#env-var_resolution-req-0001) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0001 — Declared import dependency collection + Rule: ENV-VAR_RESOLUTION-REQ-0001 — Declared import dependency collection - Scenario: ENV_VAR_RESOLUTION-ACC-0002 — Fallback variable reference is collected + Scenario: ENV-VAR_RESOLUTION-ACC-0002 — Fallback variable reference is collected Given a declaration fallback references "$HOME" When the software collects import dependencies Then "HOME" is collected @@ -57,25 +56,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0003 +## ENV-VAR_RESOLUTION-ACC-0003 Name: First available import alias is selected **Links:** -- [ENV_VAR_RESOLUTION-REQ-0002](./env-var-resolution.spec.md#env_var_resolution-req-0002) +- [ENV-VAR_RESOLUTION-REQ-0002](./env-var-resolution.spec.md#env-var_resolution-req-0002) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0002 — First-found resolution + Rule: ENV-VAR_RESOLUTION-REQ-0002 — First-found resolution - Scenario: ENV_VAR_RESOLUTION-ACC-0003 — First available import alias is selected + Scenario: ENV-VAR_RESOLUTION-ACC-0003 — First available import alias is selected Given a declaration imports "USER_LANGUAGE" before "LANG" And both aliases provide a value When the software resolves the declaration @@ -84,25 +83,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0004 +## ENV-VAR_RESOLUTION-ACC-0004 Name: Fallback is used when no import alias has a value **Links:** -- [ENV_VAR_RESOLUTION-REQ-0002](./env-var-resolution.spec.md#env_var_resolution-req-0002) +- [ENV-VAR_RESOLUTION-REQ-0002](./env-var-resolution.spec.md#env-var_resolution-req-0002) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0002 — First-found resolution + Rule: ENV-VAR_RESOLUTION-REQ-0002 — First-found resolution - Scenario: ENV_VAR_RESOLUTION-ACC-0004 — Fallback is used when no import alias has a value + Scenario: ENV-VAR_RESOLUTION-ACC-0004 — Fallback is used when no import alias has a value Given no import alias provides a value And the declaration fallback is "C.UTF-8" When the software resolves the declaration @@ -111,25 +110,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0005 +## ENV-VAR_RESOLUTION-ACC-0005 Name: Non-empty path aliases are merged in declaration order **Links:** -- [ENV_VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env_var_resolution-req-0003) +- [ENV-VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env-var_resolution-req-0003) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0003 — Path merge resolution + Rule: ENV-VAR_RESOLUTION-REQ-0003 — Path merge resolution - Scenario: ENV_VAR_RESOLUTION-ACC-0005 — Non-empty path aliases are merged in declaration order + Scenario: ENV-VAR_RESOLUTION-ACC-0005 — Non-empty path aliases are merged in declaration order Given a declaration imports "BIN_A" before "BIN_B" And "BIN_A" provides "/custom/bin" And "BIN_B" provides "/usr/bin" @@ -139,25 +138,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0006 +## ENV-VAR_RESOLUTION-ACC-0006 Name: Merge fallback is used when no path is available **Links:** -- [ENV_VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env_var_resolution-req-0003) +- [ENV-VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env-var_resolution-req-0003) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0003 — Path merge resolution + Rule: ENV-VAR_RESOLUTION-REQ-0003 — Path merge resolution - Scenario: ENV_VAR_RESOLUTION-ACC-0006 — Merge fallback is used when no path is available + Scenario: ENV-VAR_RESOLUTION-ACC-0006 — Merge fallback is used when no path is available Given no import alias provides a non-empty path value And the declaration fallback is "/usr/share/man" When the software resolves the declaration @@ -166,25 +165,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0007 +## ENV-VAR_RESOLUTION-ACC-0007 Name: Tilde fallback expands from resolved home **Links:** -- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) +- [ENV-VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env-var_resolution-req-0004) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + Rule: ENV-VAR_RESOLUTION-REQ-0004 — Placeholder expansion - Scenario: ENV_VAR_RESOLUTION-ACC-0007 — Tilde fallback expands from resolved home + Scenario: ENV-VAR_RESOLUTION-ACC-0007 — Tilde fallback expands from resolved home Given "HOME" resolves to "/workspace" And a declaration fallback is "~/.cache" When the software resolves the declaration @@ -193,25 +192,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0008 +## ENV-VAR_RESOLUTION-ACC-0008 Name: Dollar fallback expands from a collected value **Links:** -- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) +- [ENV-VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env-var_resolution-req-0004) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + Rule: ENV-VAR_RESOLUTION-REQ-0004 — Placeholder expansion - Scenario: ENV_VAR_RESOLUTION-ACC-0008 — Dollar fallback expands from a collected value + Scenario: ENV-VAR_RESOLUTION-ACC-0008 — Dollar fallback expands from a collected value Given "HOME" has the collected value "/workspace" And a declaration fallback is "$HOME/.cache" When the software resolves the declaration @@ -220,25 +219,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0009 +## ENV-VAR_RESOLUTION-ACC-0009 Name: Unresolved placeholder remains literal **Links:** -- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) +- [ENV-VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env-var_resolution-req-0004) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + Rule: ENV-VAR_RESOLUTION-REQ-0004 — Placeholder expansion - Scenario: ENV_VAR_RESOLUTION-ACC-0009 — Unresolved placeholder remains literal + Scenario: ENV-VAR_RESOLUTION-ACC-0009 — Unresolved placeholder remains literal Given a declaration fallback is "$UNKNOWN/.cache" And "UNKNOWN" has no resolved value When the software resolves the declaration @@ -247,25 +246,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0010 +## ENV-VAR_RESOLUTION-ACC-0010 Name: Empty first-found value is selected **Links:** -- [ENV_VAR_RESOLUTION-REQ-0002](./env-var-resolution.spec.md#env_var_resolution-req-0002) +- [ENV-VAR_RESOLUTION-REQ-0002](./env-var-resolution.spec.md#env-var_resolution-req-0002) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0002 — First-found resolution + Rule: ENV-VAR_RESOLUTION-REQ-0002 — First-found resolution - Scenario: ENV_VAR_RESOLUTION-ACC-0010 — Empty first-found value is selected + Scenario: ENV-VAR_RESOLUTION-ACC-0010 — Empty first-found value is selected Given a declaration imports "PRIMARY" before "SECONDARY" And "PRIMARY" has the collected value "" And "SECONDARY" has the collected value "fallback-value" @@ -275,25 +274,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0011 +## ENV-VAR_RESOLUTION-ACC-0011 Name: Provided canonical value precedes fallback **Links:** -- [ENV_VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env_var_resolution-req-0005) +- [ENV-VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env-var_resolution-req-0005) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0005 — Source precedence and absence + Rule: ENV-VAR_RESOLUTION-REQ-0005 — Source precedence and absence - Scenario: ENV_VAR_RESOLUTION-ACC-0011 — Provided canonical value precedes fallback + Scenario: ENV-VAR_RESOLUTION-ACC-0011 — Provided canonical value precedes fallback Given a provided declaration has no import aliases And its canonical key has the collected value "/custom/tmp" And its fallback is "/default/tmp" @@ -303,25 +302,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0012 +## ENV-VAR_RESOLUTION-ACC-0012 Name: Provided fallback is used when canonical value is absent **Links:** -- [ENV_VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env_var_resolution-req-0005) +- [ENV-VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env-var_resolution-req-0005) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0005 — Source precedence and absence + Rule: ENV-VAR_RESOLUTION-REQ-0005 — Source precedence and absence - Scenario: ENV_VAR_RESOLUTION-ACC-0012 — Provided fallback is used when canonical value is absent + Scenario: ENV-VAR_RESOLUTION-ACC-0012 — Provided fallback is used when canonical value is absent Given a provided declaration has no import aliases And its canonical key has no collected value And its fallback is "/default/tmp" @@ -331,25 +330,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0013 +## ENV-VAR_RESOLUTION-ACC-0013 Name: Host declaration without aliases ignores its canonical collected value **Links:** -- [ENV_VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env_var_resolution-req-0005) +- [ENV-VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env-var_resolution-req-0005) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0005 — Source precedence and absence + Rule: ENV-VAR_RESOLUTION-REQ-0005 — Source precedence and absence - Scenario: ENV_VAR_RESOLUTION-ACC-0013 — Host declaration without aliases ignores its canonical collected value + Scenario: ENV-VAR_RESOLUTION-ACC-0013 — Host declaration without aliases ignores its canonical collected value Given a host declaration has no import aliases And its canonical key has the collected value "Linux" And its fallback is "Darwin" @@ -359,25 +358,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0014 +## ENV-VAR_RESOLUTION-ACC-0014 Name: Empty path values are ignored during merge **Links:** -- [ENV_VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env_var_resolution-req-0003) +- [ENV-VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env-var_resolution-req-0003) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0003 — Path merge resolution + Rule: ENV-VAR_RESOLUTION-REQ-0003 — Path merge resolution - Scenario: ENV_VAR_RESOLUTION-ACC-0014 — Empty path values are ignored during merge + Scenario: ENV-VAR_RESOLUTION-ACC-0014 — Empty path values are ignored during merge Given a merge declaration imports "BIN_A" before "BIN_B" And "BIN_A" has the collected value "" And "BIN_B" has the collected value "/usr/bin" @@ -387,25 +386,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0015 +## ENV-VAR_RESOLUTION-ACC-0015 Name: Merged paths use the current platform separator **Links:** -- [ENV_VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env_var_resolution-req-0003) +- [ENV-VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env-var_resolution-req-0003) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0003 — Path merge resolution + Rule: ENV-VAR_RESOLUTION-REQ-0003 — Path merge resolution - Scenario: ENV_VAR_RESOLUTION-ACC-0015 — Merged paths use the current platform separator + Scenario: ENV-VAR_RESOLUTION-ACC-0015 — Merged paths use the current platform separator Given a merge declaration has two non-empty path values When the software resolves the declaration Then its paths are joined with the current platform path separator @@ -414,25 +413,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0016 +## ENV-VAR_RESOLUTION-ACC-0016 Name: Tilde expansion takes precedence and replaces only the first tilde **Links:** -- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) +- [ENV-VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env-var_resolution-req-0004) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + Rule: ENV-VAR_RESOLUTION-REQ-0004 — Placeholder expansion - Scenario: ENV_VAR_RESOLUTION-ACC-0016 — Tilde expansion takes precedence and replaces only the first tilde + Scenario: ENV-VAR_RESOLUTION-ACC-0016 — Tilde expansion takes precedence and replaces only the first tilde Given "HOME" has the collected value "/workspace" And a declaration fallback is "~/$HOME/~" When the software resolves the declaration @@ -441,25 +440,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0017 +## ENV-VAR_RESOLUTION-ACC-0017 Name: Invalid dollar syntax remains literal **Links:** -- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) +- [ENV-VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env-var_resolution-req-0004) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + Rule: ENV-VAR_RESOLUTION-REQ-0004 — Placeholder expansion - Scenario Outline: ENV_VAR_RESOLUTION-ACC-0017 — Invalid dollar syntax remains literal + Scenario Outline: ENV-VAR_RESOLUTION-ACC-0017 — Invalid dollar syntax remains literal Given a declaration fallback is "" When the software resolves the declaration Then the declaration resolves to "" @@ -473,25 +472,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0018 +## ENV-VAR_RESOLUTION-ACC-0018 Name: Dollar expansion replaces only the first placeholder **Links:** -- [ENV_VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env_var_resolution-req-0004) +- [ENV-VAR_RESOLUTION-REQ-0004](./env-var-resolution.spec.md#env-var_resolution-req-0004) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0004 — Placeholder expansion + Rule: ENV-VAR_RESOLUTION-REQ-0004 — Placeholder expansion - Scenario: ENV_VAR_RESOLUTION-ACC-0018 — Dollar expansion replaces only the first placeholder + Scenario: ENV-VAR_RESOLUTION-ACC-0018 — Dollar expansion replaces only the first placeholder Given "HOME" has the collected value "/workspace" And a declaration fallback is "$HOME/$HOME" When the software resolves the declaration @@ -500,25 +499,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0019 +## ENV-VAR_RESOLUTION-ACC-0019 Name: Pass-through forwards the first available value **Links:** -- [ENV_VAR_RESOLUTION-REQ-0006](./env-var-resolution.spec.md#env_var_resolution-req-0006) +- [ENV-VAR_RESOLUTION-REQ-0006](./env-var-resolution.spec.md#env-var_resolution-req-0006) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0006 — Pass-through resolution + Rule: ENV-VAR_RESOLUTION-REQ-0006 — Pass-through resolution - Scenario: ENV_VAR_RESOLUTION-ACC-0019 — Pass-through forwards the first available value + Scenario: ENV-VAR_RESOLUTION-ACC-0019 — Pass-through forwards the first available value Given a pass-through declaration imports "SystemRoot" And "SystemRoot" has the collected value "C:\\Windows" When the software resolves the declaration @@ -527,25 +526,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0020 +## ENV-VAR_RESOLUTION-ACC-0020 Name: Pass-through absence resolves to an empty value **Links:** -- [ENV_VAR_RESOLUTION-REQ-0006](./env-var-resolution.spec.md#env_var_resolution-req-0006) +- [ENV-VAR_RESOLUTION-REQ-0006](./env-var-resolution.spec.md#env-var_resolution-req-0006) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0006 — Pass-through resolution + Rule: ENV-VAR_RESOLUTION-REQ-0006 — Pass-through resolution - Scenario: ENV_VAR_RESOLUTION-ACC-0020 — Pass-through absence resolves to an empty value + Scenario: ENV-VAR_RESOLUTION-ACC-0020 — Pass-through absence resolves to an empty value Given a pass-through declaration imports "SystemRoot" And "SystemRoot" has no collected value When the software resolves the declaration @@ -554,25 +553,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0021 +## ENV-VAR_RESOLUTION-ACC-0021 Name: Unjoinable merged paths resolve to an empty value **Links:** -- [ENV_VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env_var_resolution-req-0003) +- [ENV-VAR_RESOLUTION-REQ-0003](./env-var-resolution.spec.md#env-var_resolution-req-0003) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0003 — Path merge resolution + Rule: ENV-VAR_RESOLUTION-REQ-0003 — Path merge resolution - Scenario: ENV_VAR_RESOLUTION-ACC-0021 — Unjoinable merged paths resolve to an empty value + Scenario: ENV-VAR_RESOLUTION-ACC-0021 — Unjoinable merged paths resolve to an empty value Given a merge declaration has paths that cannot be joined for the current platform When the software resolves the declaration Then the declaration resolves to "" @@ -580,25 +579,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0022 +## ENV-VAR_RESOLUTION-ACC-0022 Name: Missing source and fallback resolve to an empty value **Links:** -- [ENV_VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env_var_resolution-req-0005) +- [ENV-VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env-var_resolution-req-0005) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0005 — Source precedence and absence + Rule: ENV-VAR_RESOLUTION-REQ-0005 — Source precedence and absence - Scenario: ENV_VAR_RESOLUTION-ACC-0022 — Missing source and fallback resolve to an empty value + Scenario: ENV-VAR_RESOLUTION-ACC-0022 — Missing source and fallback resolve to an empty value Given a host declaration has no import aliases And the declaration has no fallback When the software resolves the declaration @@ -607,25 +606,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0023 +## ENV-VAR_RESOLUTION-ACC-0023 Name: Empty provided canonical value precedes fallback **Links:** -- [ENV_VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env_var_resolution-req-0005) +- [ENV-VAR_RESOLUTION-REQ-0005](./env-var-resolution.spec.md#env-var_resolution-req-0005) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0005 — Source precedence and absence + Rule: ENV-VAR_RESOLUTION-REQ-0005 — Source precedence and absence - Scenario: ENV_VAR_RESOLUTION-ACC-0023 — Empty provided canonical value precedes fallback + Scenario: ENV-VAR_RESOLUTION-ACC-0023 — Empty provided canonical value precedes fallback Given a provided declaration has no import aliases And its canonical key has the collected value "" And its fallback is "/default/tmp" @@ -635,25 +634,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0024 +## ENV-VAR_RESOLUTION-ACC-0024 Name: Resolved output preserves declaration and export order **Links:** -- [ENV_VAR_RESOLUTION-REQ-0007](./env-var-resolution.spec.md#env_var_resolution-req-0007) +- [ENV-VAR_RESOLUTION-REQ-0007](./env-var-resolution.spec.md#env-var_resolution-req-0007) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0007 — Resolved output order + Rule: ENV-VAR_RESOLUTION-REQ-0007 — Resolved output order - Scenario: ENV_VAR_RESOLUTION-ACC-0024 — Resolved output preserves declaration and export order + Scenario: ENV-VAR_RESOLUTION-ACC-0024 — Resolved output preserves declaration and export order Given "HOME_TEMP" resolves to "/workspace/.tmp" And its export aliases are "TEMP", "TMPDIR", and "TMP" in that order When the software resolves the declaration @@ -663,25 +662,25 @@ Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution --- -## ENV_VAR_RESOLUTION-ACC-0025 +## ENV-VAR_RESOLUTION-ACC-0025 Name: Collected keys are deduplicated and sorted **Links:** -- [ENV_VAR_RESOLUTION-REQ-0001](./env-var-resolution.spec.md#env_var_resolution-req-0001) +- [ENV-VAR_RESOLUTION-REQ-0001](./env-var-resolution.spec.md#env-var_resolution-req-0001) **Status**: -- Acceptance status: Draft -- Verification status: Not verified +- Doc status: Draft +- Verification status: Unknown ```gherkin -Feature: ENV_VAR_RESOLUTION-FEAT-0001 — Environment variable resolution +Feature: ENV-VAR_RESOLUTION-FEAT-0001 — Environment variable resolution - Rule: ENV_VAR_RESOLUTION-REQ-0001 — Declared import dependency collection + Rule: ENV-VAR_RESOLUTION-REQ-0001 — Declared import dependency collection - Scenario: ENV_VAR_RESOLUTION-ACC-0025 — Collected keys are deduplicated and sorted + Scenario: ENV-VAR_RESOLUTION-ACC-0025 — Collected keys are deduplicated and sorted Given active mappings declare the import aliases "SHELL", "EDITOR", and "SHELL" When the software collects import dependencies Then the collected import keys are "EDITOR" and "SHELL" in that order diff --git a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md index 08389d3..db8f58c 100644 --- a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md +++ b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md @@ -2,7 +2,6 @@ title: Environment variables resolution - SPEC summary: Requirements for resolving declared environment variables. tags: [environment, env-var, specification, spec, resolution] -status: draft --- > [!IMPORTANT] @@ -15,21 +14,22 @@ status: draft ## Requirements -### ENV_VAR_RESOLUTION-REQ-0001 +### ENV-VAR_RESOLUTION-REQ-0001 Name: Declared import dependency collection **Links:** -- [ENV_VAR_RESOLUTION-ACC-0001](./env-var-resolution.acceptance.md#env_var_resolution-acc-0001) -- [ENV_VAR_RESOLUTION-ACC-0002](./env-var-resolution.acceptance.md#env_var_resolution-acc-0002) -- [ENV_VAR_RESOLUTION-ACC-0025](./env-var-resolution.acceptance.md#env_var_resolution-acc-0025) +- [ENV-VAR_RESOLUTION-ACC-0001](./env-var-resolution.acceptance.md#env-var_resolution-acc-0001) +- [ENV-VAR_RESOLUTION-ACC-0002](./env-var-resolution.acceptance.md#env-var_resolution-acc-0002) +- [ENV-VAR_RESOLUTION-ACC-0025](./env-var-resolution.acceptance.md#env-var_resolution-acc-0025) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Implemented -- Verification status: Not verified **SHALL:** The software collects only import aliases and the first valid dollar variable reference in a declaration fallback. @@ -39,25 +39,26 @@ import and export keys. --- -### ENV_VAR_RESOLUTION-REQ-0002 +### ENV-VAR_RESOLUTION-REQ-0002 Name: First-found resolution **Links:** -- [ENV_VAR_RESOLUTION-ACC-0003](./env-var-resolution.acceptance.md#env_var_resolution-acc-0003) -- [ENV_VAR_RESOLUTION-ACC-0004](./env-var-resolution.acceptance.md#env_var_resolution-acc-0004) -- [ENV_VAR_RESOLUTION-ACC-0010](./env-var-resolution.acceptance.md#env_var_resolution-acc-0010) +- [ENV-VAR_RESOLUTION-ACC-0003](./env-var-resolution.acceptance.md#env-var_resolution-acc-0003) +- [ENV-VAR_RESOLUTION-ACC-0004](./env-var-resolution.acceptance.md#env-var_resolution-acc-0004) +- [ENV-VAR_RESOLUTION-ACC-0010](./env-var-resolution.acceptance.md#env-var_resolution-acc-0010) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Implemented -- Verification status: Not verified **SHALL:** A declaration using first-found import mode resolves the first -available import alias in declaration order. A collected value is available -when it is present, including when its value is empty. +available import alias in declaration order. A collected value is available when +it is present, including when its value is empty. **WHEN:** No import alias provides a value, @@ -65,28 +66,29 @@ when it is present, including when its value is empty. --- -### ENV_VAR_RESOLUTION-REQ-0003 +### ENV-VAR_RESOLUTION-REQ-0003 Name: Path merge resolution **Links:** -- [ENV_VAR_RESOLUTION-ACC-0005](./env-var-resolution.acceptance.md#env_var_resolution-acc-0005) -- [ENV_VAR_RESOLUTION-ACC-0006](./env-var-resolution.acceptance.md#env_var_resolution-acc-0006) -- [ENV_VAR_RESOLUTION-ACC-0014](./env-var-resolution.acceptance.md#env_var_resolution-acc-0014) -- [ENV_VAR_RESOLUTION-ACC-0015](./env-var-resolution.acceptance.md#env_var_resolution-acc-0015) -- [ENV_VAR_RESOLUTION-ACC-0021](./env-var-resolution.acceptance.md#env_var_resolution-acc-0021) +- [ENV-VAR_RESOLUTION-ACC-0005](./env-var-resolution.acceptance.md#env-var_resolution-acc-0005) +- [ENV-VAR_RESOLUTION-ACC-0006](./env-var-resolution.acceptance.md#env-var_resolution-acc-0006) +- [ENV-VAR_RESOLUTION-ACC-0014](./env-var-resolution.acceptance.md#env-var_resolution-acc-0014) +- [ENV-VAR_RESOLUTION-ACC-0015](./env-var-resolution.acceptance.md#env-var_resolution-acc-0015) +- [ENV-VAR_RESOLUTION-ACC-0021](./env-var-resolution.acceptance.md#env-var_resolution-acc-0021) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Implemented -- Verification status: Not verified **SHALL:** A declaration using merge import mode ignores empty imported values, -splits each remaining value into paths using the current platform semantics, -and joins the resulting paths in declaration order using the current platform -path separator. +splits each remaining value into paths using the current platform semantics, and +joins the resulting paths in declaration order using the current platform path +separator. **SHALL NOT:** Merge resolution deduplicates path entries. @@ -101,39 +103,40 @@ current platform, --- -### ENV_VAR_RESOLUTION-REQ-0004 +### ENV-VAR_RESOLUTION-REQ-0004 Name: Placeholder expansion **Links:** -- [ENV_VAR_RESOLUTION-ACC-0007](./env-var-resolution.acceptance.md#env_var_resolution-acc-0007) -- [ENV_VAR_RESOLUTION-ACC-0008](./env-var-resolution.acceptance.md#env_var_resolution-acc-0008) -- [ENV_VAR_RESOLUTION-ACC-0009](./env-var-resolution.acceptance.md#env_var_resolution-acc-0009) -- [ENV_VAR_RESOLUTION-ACC-0016](./env-var-resolution.acceptance.md#env_var_resolution-acc-0016) -- [ENV_VAR_RESOLUTION-ACC-0017](./env-var-resolution.acceptance.md#env_var_resolution-acc-0017) -- [ENV_VAR_RESOLUTION-ACC-0018](./env-var-resolution.acceptance.md#env_var_resolution-acc-0018) +- [ENV-VAR_RESOLUTION-ACC-0007](./env-var-resolution.acceptance.md#env-var_resolution-acc-0007) +- [ENV-VAR_RESOLUTION-ACC-0008](./env-var-resolution.acceptance.md#env-var_resolution-acc-0008) +- [ENV-VAR_RESOLUTION-ACC-0009](./env-var-resolution.acceptance.md#env-var_resolution-acc-0009) +- [ENV-VAR_RESOLUTION-ACC-0016](./env-var-resolution.acceptance.md#env-var_resolution-acc-0016) +- [ENV-VAR_RESOLUTION-ACC-0017](./env-var-resolution.acceptance.md#env-var_resolution-acc-0017) +- [ENV-VAR_RESOLUTION-ACC-0018](./env-var-resolution.acceptance.md#env-var_resolution-acc-0018) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Implemented -- Verification status: Not verified **SHALL:** When a fallback contains a tilde and a non-empty collected `HOME` value is available, the software replaces the first tilde with that value. -**SHALL:** When a non-empty collected `HOME` value is available, tilde -expansion takes precedence over dollar expansion. +**SHALL:** When a non-empty collected `HOME` value is available, tilde expansion +takes precedence over dollar expansion. -**WHEN:** A fallback contains a tilde but no non-empty collected `HOME` value -is available, +**WHEN:** A fallback contains a tilde but no non-empty collected `HOME` value is +available, **THE SOFTWARE SHALL:** leave the tilde unchanged and evaluate a dollar placeholder when one is present. -**SHALL:** A dollar placeholder is the first dollar sign followed by one or -more ASCII letters, digits, or underscores. The software replaces the first +**SHALL:** A dollar placeholder is the first dollar sign followed by one or more +ASCII letters, digits, or underscores. The software replaces the first occurrence of that placeholder with the collected value whose key matches its name, including an empty value. @@ -144,27 +147,28 @@ has no collected value, --- -### ENV_VAR_RESOLUTION-REQ-0005 +### ENV-VAR_RESOLUTION-REQ-0005 Name: Source precedence and absence **Links:** -- [ENV_VAR_RESOLUTION-ACC-0011](./env-var-resolution.acceptance.md#env_var_resolution-acc-0011) -- [ENV_VAR_RESOLUTION-ACC-0012](./env-var-resolution.acceptance.md#env_var_resolution-acc-0012) -- [ENV_VAR_RESOLUTION-ACC-0013](./env-var-resolution.acceptance.md#env_var_resolution-acc-0013) -- [ENV_VAR_RESOLUTION-ACC-0022](./env-var-resolution.acceptance.md#env_var_resolution-acc-0022) -- [ENV_VAR_RESOLUTION-ACC-0023](./env-var-resolution.acceptance.md#env_var_resolution-acc-0023) +- [ENV-VAR_RESOLUTION-ACC-0011](./env-var-resolution.acceptance.md#env-var_resolution-acc-0011) +- [ENV-VAR_RESOLUTION-ACC-0012](./env-var-resolution.acceptance.md#env-var_resolution-acc-0012) +- [ENV-VAR_RESOLUTION-ACC-0013](./env-var-resolution.acceptance.md#env-var_resolution-acc-0013) +- [ENV-VAR_RESOLUTION-ACC-0022](./env-var-resolution.acceptance.md#env-var_resolution-acc-0022) +- [ENV-VAR_RESOLUTION-ACC-0023](./env-var-resolution.acceptance.md#env-var_resolution-acc-0023) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Implemented -- Verification status: Not verified -**SHALL:** A declaration without import aliases and with source `Provided` -uses its collected canonical value when it is present, including when the value -is empty. +**SHALL:** A declaration without import aliases and with source `Provided` uses +its collected canonical value when it is present, including when the value is +empty. **WHEN:** That provided canonical value is absent, @@ -179,20 +183,21 @@ its fallback without reading a collected value for its canonical key. --- -### ENV_VAR_RESOLUTION-REQ-0006 +### ENV-VAR_RESOLUTION-REQ-0006 Name: Pass-through resolution **Links:** -- [ENV_VAR_RESOLUTION-ACC-0019](./env-var-resolution.acceptance.md#env_var_resolution-acc-0019) -- [ENV_VAR_RESOLUTION-ACC-0020](./env-var-resolution.acceptance.md#env_var_resolution-acc-0020) +- [ENV-VAR_RESOLUTION-ACC-0019](./env-var-resolution.acceptance.md#env-var_resolution-acc-0019) +- [ENV-VAR_RESOLUTION-ACC-0020](./env-var-resolution.acceptance.md#env-var_resolution-acc-0020) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Implemented -- Verification status: Not verified **SHALL:** A declaration using pass-through import mode resolves the first available import alias in declaration order without applying a fallback. @@ -203,19 +208,20 @@ available import alias in declaration order without applying a fallback. --- -### ENV_VAR_RESOLUTION-REQ-0007 +### ENV-VAR_RESOLUTION-REQ-0007 Name: Resolved output order **Links:** -- [ENV_VAR_RESOLUTION-ACC-0024](./env-var-resolution.acceptance.md#env_var_resolution-acc-0024) +- [ENV-VAR_RESOLUTION-ACC-0024](./env-var-resolution.acceptance.md#env-var_resolution-acc-0024) + +- [Intent](../env-var-intent.md): module intent. **Status**: -- Requirement status: Draft +- Doc status: Draft - Implementation status: Implemented -- Verification status: Not verified **SHALL:** The software emits resolved declarations in active mapping order. From 81d76ac1171a35486b1bc4d7ac89801cbfc69996 Mon Sep 17 00:00:00 2001 From: "Alex G. Wolff" <13754094+alexgwolff@users.noreply.github.com> Date: Tue, 22 Sep 2026 21:36:56 -0300 Subject: [PATCH 05/15] fixes Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com> --- .github/workflows/pull-request.yml | 2 +- cspell.json | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index f63ae35..82aa1ef 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -3,7 +3,7 @@ name: Pull Request on: pull_request: paths-ignore: - - **/*.md + - '**/*.md' permissions: contents: read diff --git a/cspell.json b/cspell.json index 7b18762..ab9213a 100644 --- a/cspell.json +++ b/cspell.json @@ -1,6 +1,6 @@ { "language": "en", - "dictionaries": ["cpp", "filetypes", "go", "powershell", "softwareTerms", "misc"], + "dictionaries": ["cpp", "filetypes", "go", "powershell", "softwareTerms", "misc", "bash"], "ignorePaths": ["cspell.json"], "words": [ "ltsc", @@ -16,6 +16,8 @@ "clippy", "worktrees", "moby", - "buildkit" + "buildkit", + "nocolor", + "preresolved" ] } From 44156c8917c98a7fd5cc275abce8d235a28ebddf Mon Sep 17 00:00:00 2001 From: Alex Godoy Wolff <13754094+alexgwolff@users.noreply.github.com> Date: Wed, 23 Sep 2026 00:41:29 -0300 Subject: [PATCH 06/15] Update .gitignore to include SPECIFICATIONS.md Remove SPECIFICATIONS.md from being ignored Signed-off-by: Alex Godoy Wolff <13754094+alexgwolff@users.noreply.github.com> --- .gitignore | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 61043c9..18d53d1 100644 --- a/.gitignore +++ b/.gitignore @@ -77,9 +77,8 @@ !/README.md !/AGENTS.md !/BUILDING.md -!/SPECIFICATIONS.md !/LICENSE !/.agents !/.agents/** -!/.agents/**/* \ No newline at end of file +!/.agents/**/* From 2117ad6637e2d0335f5e5e37f289716347e5c2db Mon Sep 17 00:00:00 2001 From: "Alex G. Wolff" <13754094+alexgwolff@users.noreply.github.com> Date: Fri, 25 Sep 2026 17:13:27 -0300 Subject: [PATCH 07/15] temp Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com> --- README.md | 22 +++++++++++----------- cspell.json => cspell.jsonc | 5 +++-- docs/README.md | 4 +++- docs/example/example.spec.md | 4 +++- 4 files changed, 20 insertions(+), 15 deletions(-) rename cspell.json => cspell.jsonc (90%) diff --git a/README.md b/README.md index d7d395e..91a6a6e 100644 --- a/README.md +++ b/README.md @@ -2,24 +2,24 @@ Kraf is a neutral layer for humans and autonomous agents, designed to provide a consistent way to work with software projects across tools, environments, and -vendors — without vendor lock-in. The goal is to start a development -environment with the least possible friction, and fast. +vendors — without vendor lock-in. The goal is to start a development environment +with the least possible friction, and fast. ## Summary Kraf explores a portable, vendor-neutral foundation for developer and agent -environments. Rather than replacing the tools, configuration files, or -workflows a project already uses, Kraf resolves them into an environment -plan, then materializes it wherever it's needed — a local shell today; CI, -containers, or an airgapped agent later. Materialization targets change; -the resolved plan doesn't. +environments. Rather than replacing the tools, configuration files, or workflows +a project already uses, Kraf resolves them into an environment plan, then +materializes it wherever it's needed — a local shell today; CI, containers, or +an airgapped agent later. Materialization targets change; the resolved plan +doesn't. Kraf's guiding rule: **materialize only what the workload proves it needs.** -The project is currently under active development. Its first working slice -is environment variable resolution and isolation — an isolated `HOME` and -working directory per run, real system state passed through deliberately -rather than by accident — materialized into a shell you can use today. +The project is currently under active development. Its first working slice is +environment variable resolution and isolation — an isolated `HOME` and working +directory per run, real system state passed through deliberately rather than by +accident — materialized into a shell you can use today. ## Contributing diff --git a/cspell.json b/cspell.jsonc similarity index 90% rename from cspell.json rename to cspell.jsonc index ab9213a..803331a 100644 --- a/cspell.json +++ b/cspell.jsonc @@ -18,6 +18,7 @@ "moby", "buildkit", "nocolor", - "preresolved" - ] + "preresolved", + "airgapped", + ], } diff --git a/docs/README.md b/docs/README.md index 835e109..c5dacc4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -173,7 +173,7 @@ THEN THE SOFTWARE SHALL . **Layout:** -```md +````md --- title: - SPEC summary: @@ -204,10 +204,12 @@ Name: - Doc status: Draft - Implementation status: Not implemented +```text **WHEN:** , **THE SOFTWARE SHALL:** . ``` +```` ### Acceptance (*.acceptance.md) diff --git a/docs/example/example.spec.md b/docs/example/example.spec.md index d343bfd..8820387 100644 --- a/docs/example/example.spec.md +++ b/docs/example/example.spec.md @@ -20,14 +20,16 @@ Name: Explicit configuration **Links:** -- [EXAMPLE_AREA-ACC-0001](./example.acceptance.md#example_area-acc-0001) - [Intent](../example-intent.md) +- [EXAMPLE_AREA-ACC-0001](./example.acceptance.md#example_area-acc-0001) **Status**: - Doc status: Draft - Implementation status: Not implemented +```text **WHEN:** Configuration provides an unknown key, **THE SOFTWARE SHALL:** reject the configuration. +``` From c630fb324ce4eb85918a20bfaa45ee1f1fd9f276 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 26 Sep 2026 16:37:27 +0000 Subject: [PATCH 08/15] docs(env-var): align specs with updated spec layout Wrap requirement statements in text blocks and list the Intent link first, matching docs/README.md and the example spec. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011uc2KL8jgKVwgzomc6Wdmp --- .../env-var-declarations.spec.md | 15 ++++---- .../docs/env-var-host/env-var-host.spec.md | 10 +++--- .../env-var-projection.spec.md | 10 +++--- .../env-var-resolution.spec.md | 35 +++++++++++-------- 4 files changed, 42 insertions(+), 28 deletions(-) diff --git a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md index 11c63ef..e66a857 100644 --- a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md +++ b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md @@ -20,16 +20,16 @@ Name: Static declaration **Links:** +- [Intent](../env-var-intent.md): module intent. - [ENV-VAR_DECLARATIONS-ACC-0001](./env-var-declarations.acceptance.md#env-var_declarations-acc-0001) - [ENV-VAR_DECLARATIONS-ACC-0002](./env-var-declarations.acceptance.md#env-var_declarations-acc-0002) -- [Intent](../env-var-intent.md): module intent. - **Status**: - Doc status: Draft - Implementation status: Not implemented +```text **SHALL:** The software resolves and projects only environment-variable declarations that are built into the software or packaged as immutable metadata with a plugin. @@ -42,6 +42,7 @@ aliases, export aliases, or source eligibility. **WHEN:** Runtime configuration provides a value for an unknown declaration, **THE SOFTWARE SHALL:** reject the configuration. +``` --- @@ -51,20 +52,21 @@ Name: Canonical key uniqueness **Links:** -- [ENV-VAR_DECLARATIONS-ACC-0003](./env-var-declarations.acceptance.md#env-var_declarations-acc-0003) - - [Intent](../env-var-intent.md): module intent. +- [ENV-VAR_DECLARATIONS-ACC-0003](./env-var-declarations.acceptance.md#env-var_declarations-acc-0003) **Status**: - Doc status: Draft - Implementation status: Partially implemented +```text **SHALL:** The software accepts at most one declaration for each canonical key. **WHEN:** A declaration set contains duplicate canonical keys, **THE SOFTWARE SHALL:** reject the declaration set. +``` --- @@ -74,17 +76,17 @@ Name: Mapping mode validity **Links:** +- [Intent](../env-var-intent.md): module intent. - [ENV-VAR_DECLARATIONS-ACC-0004](./env-var-declarations.acceptance.md#env-var_declarations-acc-0004) - [ENV-VAR_DECLARATIONS-ACC-0005](./env-var-declarations.acceptance.md#env-var_declarations-acc-0005) - [ENV-VAR_DECLARATIONS-ACC-0006](./env-var-declarations.acceptance.md#env-var_declarations-acc-0006) -- [Intent](../env-var-intent.md): module intent. - **Status**: - Doc status: Draft - Implementation status: Partially implemented +```text **SHALL:** A declaration using merge import mode declares at least two import aliases. @@ -92,3 +94,4 @@ aliases. canonical key as an import alias. **SHALL NOT:** A declaration using pass-through import mode declares a fallback. +``` diff --git a/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md b/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md index d2fa40c..05e3a3b 100644 --- a/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md +++ b/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md @@ -20,19 +20,20 @@ Name: Supported-platform mapping completeness **Links:** +- [Intent](../env-var-intent.md): module intent. - [ENV-VAR_HOST-ACC-0001](./env-var-host.acceptance.md#env-var_host-acc-0001) - [ENV-VAR_HOST-ACC-0002](./env-var-host.acceptance.md#env-var_host-acc-0002) - [ENV-VAR_HOST-ACC-0003](./env-var-host.acceptance.md#env-var_host-acc-0003) -- [Intent](../env-var-intent.md): module intent. - **Status**: - Doc status: Draft - Implementation status: Implemented +```text **SHALL:** Every supported platform mapping declares every shared canonical environment-variable key. +``` --- @@ -42,14 +43,15 @@ Name: Session-owned directory sources **Links:** -- [ENV-VAR_HOST-ACC-0004](./env-var-host.acceptance.md#env-var_host-acc-0004) - - [Intent](../env-var-intent.md): module intent. +- [ENV-VAR_HOST-ACC-0004](./env-var-host.acceptance.md#env-var_host-acc-0004) **Status**: - Doc status: Draft - Implementation status: Implemented +```text **SHALL:** The WORKDIR and HOME declaration families use provided values rather than values imported from the host. +``` diff --git a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md index b783967..8183a38 100644 --- a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md +++ b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md @@ -20,18 +20,19 @@ Name: Explicit export authorization **Links:** +- [Intent](../env-var-intent.md): module intent. - [ENV-VAR_PROJECTION-ACC-0001](./env-var-projection.acceptance.md#env-var_projection-acc-0001) - [ENV-VAR_PROJECTION-ACC-0002](./env-var-projection.acceptance.md#env-var_projection-acc-0002) -- [Intent](../env-var-intent.md): module intent. - **Status**: - Doc status: Draft - Implementation status: Implemented +```text **SHALL:** The software projects only keys declared as export aliases by the active mappings. +``` --- @@ -41,14 +42,15 @@ Name: Export value symmetry **Links:** -- [ENV-VAR_PROJECTION-ACC-0003](./env-var-projection.acceptance.md#env-var_projection-acc-0003) - - [Intent](../env-var-intent.md): module intent. +- [ENV-VAR_PROJECTION-ACC-0003](./env-var-projection.acceptance.md#env-var_projection-acc-0003) **Status**: - Doc status: Draft - Implementation status: Implemented +```text **SHALL:** Every export alias produced by a declaration has the declaration's resolved value. +``` diff --git a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md index db8f58c..8acc9a0 100644 --- a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md +++ b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md @@ -20,22 +20,23 @@ Name: Declared import dependency collection **Links:** +- [Intent](../env-var-intent.md): module intent. - [ENV-VAR_RESOLUTION-ACC-0001](./env-var-resolution.acceptance.md#env-var_resolution-acc-0001) - [ENV-VAR_RESOLUTION-ACC-0002](./env-var-resolution.acceptance.md#env-var_resolution-acc-0002) - [ENV-VAR_RESOLUTION-ACC-0025](./env-var-resolution.acceptance.md#env-var_resolution-acc-0025) -- [Intent](../env-var-intent.md): module intent. - **Status**: - Doc status: Draft - Implementation status: Implemented +```text **SHALL:** The software collects only import aliases and the first valid dollar variable reference in a declaration fallback. **SHALL:** The software deduplicates and lexicographically sorts collected import and export keys. +``` --- @@ -45,17 +46,17 @@ Name: First-found resolution **Links:** +- [Intent](../env-var-intent.md): module intent. - [ENV-VAR_RESOLUTION-ACC-0003](./env-var-resolution.acceptance.md#env-var_resolution-acc-0003) - [ENV-VAR_RESOLUTION-ACC-0004](./env-var-resolution.acceptance.md#env-var_resolution-acc-0004) - [ENV-VAR_RESOLUTION-ACC-0010](./env-var-resolution.acceptance.md#env-var_resolution-acc-0010) -- [Intent](../env-var-intent.md): module intent. - **Status**: - Doc status: Draft - Implementation status: Implemented +```text **SHALL:** A declaration using first-found import mode resolves the first available import alias in declaration order. A collected value is available when it is present, including when its value is empty. @@ -63,6 +64,7 @@ it is present, including when its value is empty. **WHEN:** No import alias provides a value, **THE SOFTWARE SHALL:** resolve the declaration fallback. +``` --- @@ -72,19 +74,19 @@ Name: Path merge resolution **Links:** +- [Intent](../env-var-intent.md): module intent. - [ENV-VAR_RESOLUTION-ACC-0005](./env-var-resolution.acceptance.md#env-var_resolution-acc-0005) - [ENV-VAR_RESOLUTION-ACC-0006](./env-var-resolution.acceptance.md#env-var_resolution-acc-0006) - [ENV-VAR_RESOLUTION-ACC-0014](./env-var-resolution.acceptance.md#env-var_resolution-acc-0014) - [ENV-VAR_RESOLUTION-ACC-0015](./env-var-resolution.acceptance.md#env-var_resolution-acc-0015) - [ENV-VAR_RESOLUTION-ACC-0021](./env-var-resolution.acceptance.md#env-var_resolution-acc-0021) -- [Intent](../env-var-intent.md): module intent. - **Status**: - Doc status: Draft - Implementation status: Implemented +```text **SHALL:** A declaration using merge import mode ignores empty imported values, splits each remaining value into paths using the current platform semantics, and joins the resulting paths in declaration order using the current platform path @@ -100,6 +102,7 @@ separator. current platform, **THE SOFTWARE SHALL:** resolve the declaration to an empty string. +``` --- @@ -109,6 +112,7 @@ Name: Placeholder expansion **Links:** +- [Intent](../env-var-intent.md): module intent. - [ENV-VAR_RESOLUTION-ACC-0007](./env-var-resolution.acceptance.md#env-var_resolution-acc-0007) - [ENV-VAR_RESOLUTION-ACC-0008](./env-var-resolution.acceptance.md#env-var_resolution-acc-0008) - [ENV-VAR_RESOLUTION-ACC-0009](./env-var-resolution.acceptance.md#env-var_resolution-acc-0009) @@ -116,13 +120,12 @@ Name: Placeholder expansion - [ENV-VAR_RESOLUTION-ACC-0017](./env-var-resolution.acceptance.md#env-var_resolution-acc-0017) - [ENV-VAR_RESOLUTION-ACC-0018](./env-var-resolution.acceptance.md#env-var_resolution-acc-0018) -- [Intent](../env-var-intent.md): module intent. - **Status**: - Doc status: Draft - Implementation status: Implemented +```text **SHALL:** When a fallback contains a tilde and a non-empty collected `HOME` value is available, the software replaces the first tilde with that value. @@ -144,6 +147,7 @@ name, including an empty value. has no collected value, **THE SOFTWARE SHALL:** preserve it literally. +``` --- @@ -153,19 +157,19 @@ Name: Source precedence and absence **Links:** +- [Intent](../env-var-intent.md): module intent. - [ENV-VAR_RESOLUTION-ACC-0011](./env-var-resolution.acceptance.md#env-var_resolution-acc-0011) - [ENV-VAR_RESOLUTION-ACC-0012](./env-var-resolution.acceptance.md#env-var_resolution-acc-0012) - [ENV-VAR_RESOLUTION-ACC-0013](./env-var-resolution.acceptance.md#env-var_resolution-acc-0013) - [ENV-VAR_RESOLUTION-ACC-0022](./env-var-resolution.acceptance.md#env-var_resolution-acc-0022) - [ENV-VAR_RESOLUTION-ACC-0023](./env-var-resolution.acceptance.md#env-var_resolution-acc-0023) -- [Intent](../env-var-intent.md): module intent. - **Status**: - Doc status: Draft - Implementation status: Implemented +```text **SHALL:** A declaration without import aliases and with source `Provided` uses its collected canonical value when it is present, including when the value is empty. @@ -180,6 +184,7 @@ its fallback without reading a collected value for its canonical key. **WHEN:** The selected source and fallback provide no value, **THE SOFTWARE SHALL:** resolve the declaration to an empty string. +``` --- @@ -189,22 +194,23 @@ Name: Pass-through resolution **Links:** +- [Intent](../env-var-intent.md): module intent. - [ENV-VAR_RESOLUTION-ACC-0019](./env-var-resolution.acceptance.md#env-var_resolution-acc-0019) - [ENV-VAR_RESOLUTION-ACC-0020](./env-var-resolution.acceptance.md#env-var_resolution-acc-0020) -- [Intent](../env-var-intent.md): module intent. - **Status**: - Doc status: Draft - Implementation status: Implemented +```text **SHALL:** A declaration using pass-through import mode resolves the first available import alias in declaration order without applying a fallback. **WHEN:** No import alias provides a value, **THE SOFTWARE SHALL:** resolve the declaration to an empty string. +``` --- @@ -214,17 +220,18 @@ Name: Resolved output order **Links:** -- [ENV-VAR_RESOLUTION-ACC-0024](./env-var-resolution.acceptance.md#env-var_resolution-acc-0024) - - [Intent](../env-var-intent.md): module intent. +- [ENV-VAR_RESOLUTION-ACC-0024](./env-var-resolution.acceptance.md#env-var_resolution-acc-0024) **Status**: - Doc status: Draft - Implementation status: Implemented +```text **SHALL:** The software emits resolved declarations in active mapping order. **SHALL:** For each declaration, the software emits the canonical key first, followed by its export aliases in declaration order. Every emitted key has the same resolved value. +``` From d4eb51fc6cd0ba2f8e842d08f1d5d4b3fd635bad Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 26 Sep 2026 17:20:20 +0000 Subject: [PATCH 09/15] docs(env-var): write requirements in EARS and nest intent principles Replace standalone SHALL/MAY/SHALL NOT labels with full EARS sentences whose subject is the software, move inline conditions into WHEN clauses, and nest Principles under the Intent section. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011uc2KL8jgKVwgzomc6Wdmp --- .../env-var-declarations.spec.md | 26 ++++---- .../docs/env-var-host/env-var-host.spec.md | 8 +-- .../src/env_var/docs/env-var-intent.md | 8 +-- .../env-var-projection.spec.md | 8 +-- .../env-var-resolution.spec.md | 64 ++++++++++--------- 5 files changed, 60 insertions(+), 54 deletions(-) diff --git a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md index e66a857..f9d9dea 100644 --- a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md +++ b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md @@ -30,14 +30,15 @@ Name: Static declaration - Implementation status: Not implemented ```text -**SHALL:** The software resolves and projects only environment-variable -declarations that are built into the software or packaged as immutable metadata -with a plugin. +The software SHALL resolve and project only environment-variable declarations +that are built into the software or packaged as immutable metadata with a +plugin. -**MAY:** Runtime configuration provides values for known declarations. +The software MAY accept values for known declarations from runtime +configuration. -**SHALL NOT:** Runtime configuration creates declarations or adds import -aliases, export aliases, or source eligibility. +The software SHALL NOT accept declarations, import aliases, export aliases, or +source eligibility from runtime configuration. **WHEN:** Runtime configuration provides a value for an unknown declaration, @@ -61,7 +62,7 @@ Name: Canonical key uniqueness - Implementation status: Partially implemented ```text -**SHALL:** The software accepts at most one declaration for each canonical key. +The software SHALL accept at most one declaration for each canonical key. **WHEN:** A declaration set contains duplicate canonical keys, @@ -87,11 +88,12 @@ Name: Mapping mode validity - Implementation status: Partially implemented ```text -**SHALL:** A declaration using merge import mode declares at least two import -aliases. +The software SHALL accept a declaration using merge import mode only when it +declares at least two import aliases. -**SHALL:** A declaration using pass-through import mode declares only its -canonical key as an import alias. +The software SHALL accept a declaration using pass-through import mode only when +its canonical key is its only import alias. -**SHALL NOT:** A declaration using pass-through import mode declares a fallback. +The software SHALL NOT accept a declaration using pass-through import mode that +declares a fallback. ``` diff --git a/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md b/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md index 05e3a3b..b15ad0e 100644 --- a/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md +++ b/src/environment/src/env_var/docs/env-var-host/env-var-host.spec.md @@ -31,8 +31,8 @@ Name: Supported-platform mapping completeness - Implementation status: Implemented ```text -**SHALL:** Every supported platform mapping declares every shared canonical -environment-variable key. +The software SHALL declare every shared canonical environment-variable key in +every supported platform mapping. ``` --- @@ -52,6 +52,6 @@ Name: Session-owned directory sources - Implementation status: Implemented ```text -**SHALL:** The WORKDIR and HOME declaration families use provided values rather -than values imported from the host. +The software SHALL resolve the WORKDIR and HOME declaration families from +provided values rather than from values imported from the host. ``` diff --git a/src/environment/src/env_var/docs/env-var-intent.md b/src/environment/src/env_var/docs/env-var-intent.md index 22eb5dc..3973357 100644 --- a/src/environment/src/env_var/docs/env-var-intent.md +++ b/src/environment/src/env_var/docs/env-var-intent.md @@ -28,9 +28,9 @@ The model must make it possible to: across consumers; - make the environment received by a managed process explicit and reviewable. -## Principles +### Principles -### Static declarations +#### Static declarations Environment declarations are static capabilities. @@ -43,7 +43,7 @@ Dynamic sources may provide values for existing declarations. They must not create new declarations, request undeclared host values, or expand the set of variables that a process may receive. -### Security access +#### Security access Only the environment module may read raw environment values from the host. @@ -52,7 +52,7 @@ they own or explicitly declare as a dependency. This module must not expose an operation that enumerates all host environment variables, nor arbitrary string-based host lookups outside this module. -### Explicit projection +#### Explicit projection Importing an alias and exporting a value are separate permissions. diff --git a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md index 8183a38..3b67a5e 100644 --- a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md +++ b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.spec.md @@ -30,8 +30,8 @@ Name: Explicit export authorization - Implementation status: Implemented ```text -**SHALL:** The software projects only keys declared as export aliases by the -active mappings. +The software SHALL project only keys declared as export aliases by the active +mappings. ``` --- @@ -51,6 +51,6 @@ Name: Export value symmetry - Implementation status: Implemented ```text -**SHALL:** Every export alias produced by a declaration has the declaration's -resolved value. +The software SHALL assign the declaration's resolved value to every export alias +the declaration produces. ``` diff --git a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md index 8acc9a0..a0eb607 100644 --- a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md +++ b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md @@ -31,11 +31,11 @@ Name: Declared import dependency collection - Implementation status: Implemented ```text -**SHALL:** The software collects only import aliases and the first valid dollar +The software SHALL collect only import aliases and the first valid dollar variable reference in a declaration fallback. -**SHALL:** The software deduplicates and lexicographically sorts collected -import and export keys. +The software SHALL deduplicate and lexicographically sort collected import and +export keys. ``` --- @@ -57,9 +57,9 @@ Name: First-found resolution - Implementation status: Implemented ```text -**SHALL:** A declaration using first-found import mode resolves the first -available import alias in declaration order. A collected value is available when -it is present, including when its value is empty. +The software SHALL resolve a declaration using first-found import mode to the +first available import alias in declaration order. A collected value is +available when it is present, including when its value is empty. **WHEN:** No import alias provides a value, @@ -87,12 +87,12 @@ Name: Path merge resolution - Implementation status: Implemented ```text -**SHALL:** A declaration using merge import mode ignores empty imported values, -splits each remaining value into paths using the current platform semantics, and -joins the resulting paths in declaration order using the current platform path -separator. +The software SHALL resolve a declaration using merge import mode by ignoring +empty imported values, splitting each remaining value into paths using the +current platform semantics, and joining the resulting paths in declaration order +using the current platform path separator. -**SHALL NOT:** Merge resolution deduplicates path entries. +The software SHALL NOT deduplicate path entries during merge resolution. **WHEN:** No import alias provides a non-empty path value, @@ -126,11 +126,14 @@ Name: Placeholder expansion - Implementation status: Implemented ```text -**SHALL:** When a fallback contains a tilde and a non-empty collected `HOME` -value is available, the software replaces the first tilde with that value. +**WHEN:** A fallback contains a tilde and a non-empty collected `HOME` value is +available, + +**THE SOFTWARE SHALL:** replace the first tilde with that value. + +**WHEN:** A non-empty collected `HOME` value is available, -**SHALL:** When a non-empty collected `HOME` value is available, tilde expansion -takes precedence over dollar expansion. +**THE SOFTWARE SHALL:** give tilde expansion precedence over dollar expansion. **WHEN:** A fallback contains a tilde but no non-empty collected `HOME` value is available, @@ -138,10 +141,11 @@ available, **THE SOFTWARE SHALL:** leave the tilde unchanged and evaluate a dollar placeholder when one is present. -**SHALL:** A dollar placeholder is the first dollar sign followed by one or more -ASCII letters, digits, or underscores. The software replaces the first -occurrence of that placeholder with the collected value whose key matches its -name, including an empty value. +A dollar placeholder is the first dollar sign followed by one or more ASCII +letters, digits, or underscores. + +The software SHALL replace the first occurrence of that placeholder with the +collected value whose key matches its name, including an empty value. **WHEN:** A dollar sign has no valid placeholder name or a dollar placeholder has no collected value, @@ -170,16 +174,17 @@ Name: Source precedence and absence - Implementation status: Implemented ```text -**SHALL:** A declaration without import aliases and with source `Provided` uses -its collected canonical value when it is present, including when the value is -empty. +**WHEN:** A declaration without import aliases and with source `Provided` has a +collected canonical value, including an empty value, + +**THE SOFTWARE SHALL:** resolve the declaration to that value. **WHEN:** That provided canonical value is absent, **THE SOFTWARE SHALL:** resolve the declaration fallback. -**SHALL:** A declaration without import aliases and with source `Host` resolves -its fallback without reading a collected value for its canonical key. +The software SHALL resolve a declaration without import aliases and with source +`Host` to its fallback without reading a collected value for its canonical key. **WHEN:** The selected source and fallback provide no value, @@ -204,8 +209,8 @@ Name: Pass-through resolution - Implementation status: Implemented ```text -**SHALL:** A declaration using pass-through import mode resolves the first -available import alias in declaration order without applying a fallback. +The software SHALL resolve a declaration using pass-through import mode to the +first available import alias in declaration order without applying a fallback. **WHEN:** No import alias provides a value, @@ -229,9 +234,8 @@ Name: Resolved output order - Implementation status: Implemented ```text -**SHALL:** The software emits resolved declarations in active mapping order. +The software SHALL emit resolved declarations in active mapping order. -**SHALL:** For each declaration, the software emits the canonical key first, -followed by its export aliases in declaration order. Every emitted key has the -same resolved value. +The software SHALL emit, for each declaration, the canonical key first, followed +by its export aliases in declaration order, all with the same resolved value. ``` From 4201f3deea57c8b57ac55246b5b2e5930061e353 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 26 Sep 2026 17:20:31 +0000 Subject: [PATCH 10/15] docs(env-var): use a valid example key and consistent env-var tag Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011uc2KL8jgKVwgzomc6Wdmp --- src/environment/src/env_var/README.md | 2 +- .../env-var-declarations.acceptance.md | 12 ++++++------ .../env-var-projection.acceptance.md | 12 ++++++------ 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/environment/src/env_var/README.md b/src/environment/src/env_var/README.md index 14a6ed3..9219432 100644 --- a/src/environment/src/env_var/README.md +++ b/src/environment/src/env_var/README.md @@ -1,7 +1,7 @@ --- title: Environment variables summary: Declarative model, resolution, and projection of environment variables in Kraf. -tags: [environment, env var, resolution, projection] +tags: [environment, env-var, resolution, projection] --- This module defines and resolves Kraf's declarative model for environment diff --git a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md index 25ca690..f700c2a 100644 --- a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md +++ b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.acceptance.md @@ -23,10 +23,10 @@ Feature: ENV-VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations Rule: ENV-VAR_DECLARATIONS-REQ-0001 — Static declaration Scenario: ENV-VAR_DECLARATIONS-ACC-0001 — Unknown runtime declaration is rejected - Given no declaration exists for "ENV-VAR_X" - When runtime configuration provides a value for "ENV-VAR_X" + Given no declaration exists for "EXAMPLE_KEY" + When runtime configuration provides a value for "EXAMPLE_KEY" Then the software rejects the configuration - And "ENV-VAR_X" is not projected to a managed process + And "EXAMPLE_KEY" is not projected to a managed process ``` --- @@ -50,8 +50,8 @@ Feature: ENV-VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations Rule: ENV-VAR_DECLARATIONS-REQ-0001 — Static declaration Scenario: ENV-VAR_DECLARATIONS-ACC-0002 — Known runtime declaration accepts a value - Given a declaration exists for "ENV-VAR_X" - When runtime configuration provides a value for "ENV-VAR_X" + Given a declaration exists for "EXAMPLE_KEY" + When runtime configuration provides a value for "EXAMPLE_KEY" Then the software accepts the configuration ``` @@ -76,7 +76,7 @@ Feature: ENV-VAR_DECLARATIONS-FEAT-0001 — Environment variable declarations Rule: ENV-VAR_DECLARATIONS-REQ-0002 — Canonical key uniqueness Scenario: ENV-VAR_DECLARATIONS-ACC-0003 — Duplicate canonical key is rejected - Given two declarations use the canonical key "ENV-VAR_X" + Given two declarations use the canonical key "EXAMPLE_KEY" When the software loads the declaration set Then the software rejects the declaration set ``` diff --git a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md index 3b154ed..4af077a 100644 --- a/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md +++ b/src/environment/src/env_var/docs/env-var-projection/env-var-projection.acceptance.md @@ -23,10 +23,10 @@ Feature: ENV-VAR_PROJECTION-FEAT-0001 — Environment variable projection Rule: ENV-VAR_PROJECTION-REQ-0001 — Explicit export authorization Scenario: ENV-VAR_PROJECTION-ACC-0001 — Declared export alias is projected - Given "ENV-VAR_X" is declared as an export alias - And "ENV-VAR_X" has a resolved value + Given "EXAMPLE_KEY" is declared as an export alias + And "EXAMPLE_KEY" has a resolved value When the software applies the projection to a managed process - Then the managed process receives "ENV-VAR_X" + Then the managed process receives "EXAMPLE_KEY" ``` --- @@ -50,10 +50,10 @@ Feature: ENV-VAR_PROJECTION-FEAT-0001 — Environment variable projection Rule: ENV-VAR_PROJECTION-REQ-0001 — Explicit export authorization Scenario: ENV-VAR_PROJECTION-ACC-0002 — Non-exportable resolved value is not projected - Given "ENV-VAR_X" has a resolved value - And "ENV-VAR_X" is not declared as an export alias + Given "EXAMPLE_KEY" has a resolved value + And "EXAMPLE_KEY" is not declared as an export alias When the software applies the projection to a managed process - Then the managed process does not receive "ENV-VAR_X" + Then the managed process does not receive "EXAMPLE_KEY" ``` --- From 52239890a5c87a410460c6e8b274a71c263c05ff Mon Sep 17 00:00:00 2001 From: "Alex G. Wolff" <13754094+alexgwolff@users.noreply.github.com> Date: Sat, 26 Sep 2026 14:23:59 -0300 Subject: [PATCH 11/15] temp Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com> --- BUILDING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 73263c8..4100dde 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -66,16 +66,16 @@ which Docker can't build for. ## Markdown front-matter -Every `.md` file requires frontmatter with `title`, `summary`, and `tags` — +Every `.md` file requires front-matter with `title`, `summary`, and `tags` — makes docs easy to index for agents. Exception: the root `README.md`, which -doesn't need frontmatter. Module `README.md` files do need it — see +doesn't need front-matter. Module `README.md` files do need it — see [Module README](./docs/README.md#readme-readmemd). ## Agents Don't commit AI agent config that's exclusive to a single agent (Claude-only, -Codex-only, etc.) — it lives in the dev's own environment. Config meant to -work across agents may be committed. +Codex-only, etc.) — it lives in the dev's own environment. Config meant to work +across agents may be committed. ## Code standards From 75a2a693c18c09df325a0f424511a6d289cc3417 Mon Sep 17 00:00:00 2001 From: "Alex G. Wolff" <13754094+alexgwolff@users.noreply.github.com> Date: Sat, 26 Sep 2026 14:34:11 -0300 Subject: [PATCH 12/15] fixes Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com> --- docs/README.md | 5 +++++ src/environment/src/env_var/README.md | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index c5dacc4..435c327 100644 --- a/docs/README.md +++ b/docs/README.md @@ -95,6 +95,11 @@ tags: [, , ...] > sources planned for its evolution. It does not imply that all of these > capabilities are already implemented. +## Overview + + + ## Documentation - [Intent](./docs/-intent.md): purpose, boundaries, and evolution of diff --git a/src/environment/src/env_var/README.md b/src/environment/src/env_var/README.md index 9219432..f17f4bf 100644 --- a/src/environment/src/env_var/README.md +++ b/src/environment/src/env_var/README.md @@ -12,7 +12,7 @@ aliases, and projections exported to Kraf-managed processes. > concepts and sources planned for its evolution. It does not imply that all of > these capabilities are already implemented. -## Concepts +## Overview - [**Sources**](#sources): where environment-variable values, configuration, and restrictions come from. From a88b6da17cbb8545ba396a3769ca4a6477f19fbd Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 26 Sep 2026 17:40:54 +0000 Subject: [PATCH 13/15] docs: drop bold markup inside requirement text blocks Markdown is not rendered inside text code blocks, so the bold markers showed up as literal asterisks. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011uc2KL8jgKVwgzomc6Wdmp --- docs/README.md | 4 +- docs/example/example.spec.md | 4 +- .../env-var-declarations.spec.md | 8 ++-- .../env-var-resolution.spec.md | 44 +++++++++---------- 4 files changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/README.md b/docs/README.md index 435c327..7acfeed 100644 --- a/docs/README.md +++ b/docs/README.md @@ -210,9 +210,9 @@ Name: - Implementation status: Not implemented ```text -**WHEN:** , +WHEN: , -**THE SOFTWARE SHALL:** . +THE SOFTWARE SHALL: . ``` ```` diff --git a/docs/example/example.spec.md b/docs/example/example.spec.md index 8820387..ca4d7ac 100644 --- a/docs/example/example.spec.md +++ b/docs/example/example.spec.md @@ -29,7 +29,7 @@ Name: Explicit configuration - Implementation status: Not implemented ```text -**WHEN:** Configuration provides an unknown key, +WHEN: Configuration provides an unknown key, -**THE SOFTWARE SHALL:** reject the configuration. +THE SOFTWARE SHALL: reject the configuration. ``` diff --git a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md index f9d9dea..cb44f5d 100644 --- a/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md +++ b/src/environment/src/env_var/docs/env-var-declarations/env-var-declarations.spec.md @@ -40,9 +40,9 @@ configuration. The software SHALL NOT accept declarations, import aliases, export aliases, or source eligibility from runtime configuration. -**WHEN:** Runtime configuration provides a value for an unknown declaration, +WHEN: Runtime configuration provides a value for an unknown declaration, -**THE SOFTWARE SHALL:** reject the configuration. +THE SOFTWARE SHALL: reject the configuration. ``` --- @@ -64,9 +64,9 @@ Name: Canonical key uniqueness ```text The software SHALL accept at most one declaration for each canonical key. -**WHEN:** A declaration set contains duplicate canonical keys, +WHEN: A declaration set contains duplicate canonical keys, -**THE SOFTWARE SHALL:** reject the declaration set. +THE SOFTWARE SHALL: reject the declaration set. ``` --- diff --git a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md index a0eb607..4c5603e 100644 --- a/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md +++ b/src/environment/src/env_var/docs/env-var-resolution/env-var-resolution.spec.md @@ -61,9 +61,9 @@ The software SHALL resolve a declaration using first-found import mode to the first available import alias in declaration order. A collected value is available when it is present, including when its value is empty. -**WHEN:** No import alias provides a value, +WHEN: No import alias provides a value, -**THE SOFTWARE SHALL:** resolve the declaration fallback. +THE SOFTWARE SHALL: resolve the declaration fallback. ``` --- @@ -94,14 +94,14 @@ using the current platform path separator. The software SHALL NOT deduplicate path entries during merge resolution. -**WHEN:** No import alias provides a non-empty path value, +WHEN: No import alias provides a non-empty path value, -**THE SOFTWARE SHALL:** resolve the declaration fallback. +THE SOFTWARE SHALL: resolve the declaration fallback. -**WHEN:** Joining the collected paths cannot produce a valid string for the +WHEN: Joining the collected paths cannot produce a valid string for the current platform, -**THE SOFTWARE SHALL:** resolve the declaration to an empty string. +THE SOFTWARE SHALL: resolve the declaration to an empty string. ``` --- @@ -126,19 +126,19 @@ Name: Placeholder expansion - Implementation status: Implemented ```text -**WHEN:** A fallback contains a tilde and a non-empty collected `HOME` value is +WHEN: A fallback contains a tilde and a non-empty collected `HOME` value is available, -**THE SOFTWARE SHALL:** replace the first tilde with that value. +THE SOFTWARE SHALL: replace the first tilde with that value. -**WHEN:** A non-empty collected `HOME` value is available, +WHEN: A non-empty collected `HOME` value is available, -**THE SOFTWARE SHALL:** give tilde expansion precedence over dollar expansion. +THE SOFTWARE SHALL: give tilde expansion precedence over dollar expansion. -**WHEN:** A fallback contains a tilde but no non-empty collected `HOME` value is +WHEN: A fallback contains a tilde but no non-empty collected `HOME` value is available, -**THE SOFTWARE SHALL:** leave the tilde unchanged and evaluate a dollar +THE SOFTWARE SHALL: leave the tilde unchanged and evaluate a dollar placeholder when one is present. A dollar placeholder is the first dollar sign followed by one or more ASCII @@ -147,10 +147,10 @@ letters, digits, or underscores. The software SHALL replace the first occurrence of that placeholder with the collected value whose key matches its name, including an empty value. -**WHEN:** A dollar sign has no valid placeholder name or a dollar placeholder +WHEN: A dollar sign has no valid placeholder name or a dollar placeholder has no collected value, -**THE SOFTWARE SHALL:** preserve it literally. +THE SOFTWARE SHALL: preserve it literally. ``` --- @@ -174,21 +174,21 @@ Name: Source precedence and absence - Implementation status: Implemented ```text -**WHEN:** A declaration without import aliases and with source `Provided` has a +WHEN: A declaration without import aliases and with source `Provided` has a collected canonical value, including an empty value, -**THE SOFTWARE SHALL:** resolve the declaration to that value. +THE SOFTWARE SHALL: resolve the declaration to that value. -**WHEN:** That provided canonical value is absent, +WHEN: That provided canonical value is absent, -**THE SOFTWARE SHALL:** resolve the declaration fallback. +THE SOFTWARE SHALL: resolve the declaration fallback. The software SHALL resolve a declaration without import aliases and with source `Host` to its fallback without reading a collected value for its canonical key. -**WHEN:** The selected source and fallback provide no value, +WHEN: The selected source and fallback provide no value, -**THE SOFTWARE SHALL:** resolve the declaration to an empty string. +THE SOFTWARE SHALL: resolve the declaration to an empty string. ``` --- @@ -212,9 +212,9 @@ Name: Pass-through resolution The software SHALL resolve a declaration using pass-through import mode to the first available import alias in declaration order without applying a fallback. -**WHEN:** No import alias provides a value, +WHEN: No import alias provides a value, -**THE SOFTWARE SHALL:** resolve the declaration to an empty string. +THE SOFTWARE SHALL: resolve the declaration to an empty string. ``` --- From 78fabeeeefde12bd92ddbb9ed3bcd74be11a3a1a Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 28 Sep 2026 19:07:32 +0000 Subject: [PATCH 14/15] docs: name area folders and files - in the convention Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011uc2KL8jgKVwgzomc6Wdmp --- docs/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/README.md b/docs/README.md index 7acfeed..95ba247 100644 --- a/docs/README.md +++ b/docs/README.md @@ -27,9 +27,9 @@ Documentation lives with the feature it describes. Never in root /docs / └── docs/ ├── -intent.md - └── / - ├── .spec.md - └── .acceptance.md + └── -/ + ├── -.spec.md + └── -.acceptance.md ``` Documentation does not need to map one-to-one to source files, platform files, @@ -104,8 +104,8 @@ they relate. May use subsections (###).> - [Intent](./docs/-intent.md): purpose, boundaries, and evolution of this module. -- [](./docs//.spec.md): requirements and acceptance - scenarios. +- [](./docs/-/-.spec.md): + requirements and acceptance scenarios. ``` ### Intent (*.intent.md) @@ -137,7 +137,7 @@ tags: [, , ...] ## Documentation - [Readme](../README.md): module overview. -- [](.//.spec.md): Specification. +- [](./-/-.spec.md): Specification. ``` ### Specification (*.spec.md) @@ -201,7 +201,7 @@ Name: **Links:** -- [_-ACC-0001](./.acceptance.md#_-acc-0001) +- [_-ACC-0001](./-.acceptance.md#_-acc-0001) - [Intent](../-intent.md) **Status**: @@ -266,7 +266,7 @@ Name: **Links:** -- [_-REQ-0001](./.spec.md#_-req-0001) +- [_-REQ-0001](./-.spec.md#_-req-0001) **Status**: From 71ed8fc02c3a9f268785176e4e4ce00f1391be66 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 28 Sep 2026 19:09:29 +0000 Subject: [PATCH 15/15] docs: point AGENTS.md to .agents/skills Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011uc2KL8jgKVwgzomc6Wdmp --- AGENTS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 5c04148..26491e8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,3 +5,6 @@ tags: [agents, instructions, repository, coding-conventions] --- See [BUILDING.md](./BUILDING.md) for coding rules and conventions. + +Agent skills live in [.agents/skills/](./.agents/skills/). Each skill's +`SKILL.md` front-matter describes when to use it.