"test: Add 13 WRAP_ACTIONS conformance fixtures from the coverage audit (#153)
* test: Add 13 WRAP_ACTIONS conformance fixtures
Close the conformance coverage gaps identified by the RFC 0008 deep
review and element-by-element coverage audit. Every High-severity
divergence found across the review's five passes lived on a spec-mandated
path that no fixture exercised; each new fixture pins one of those
normative statements so cross-runtime divergences surface in CI instead
of in review probes.
Run-time cancelation validation (Template Schemas 5.3, "the runtime MUST
fail the action" — previously zero fixtures; each derives its invalid
value from WrappedAction.*, seeded per-action at host evaluation time,
so the value is unknowable statically or at job creation and cannot be
constant-folded away by an eager validator):
- wrap-cancelation-mode-resolves-invalid-fails
- wrap-cancelation-terminate-with-period-fails
- wrap-cancelation-period-over-cap-fails
Instantiation-time forwarding deferral (round-trip forwarding with the
wrap env in jobEnvironments; every existing round-trip fixture used
external env templates and never passed through job creation):
- wrap-cancelation-roundtrip-job-environment
Environment-template scope carried to wrap hooks (parameters and lets
resolve in hooks; the wrapped step's symtab cannot supply them):
- wrap-env-template-parameters-in-hooks
- wrap-env-let-bindings-in-hooks
WrappedAction.Environment is openjd_env-only (4.3.1; declarative
variables: map excluded):
- wrap-environment-excludes-variables-map
Session-level single-layer rule (two wrap envs as SEPARATE environment
templates — no single template is invalid, so only the runner can
reject; the existing fixture stacks both inside one job template):
- wrap-two-wrap-env-templates-rejected
Cleanup guarantee and failure semantics (RFC scenario table, previously
zero fixtures; now expressible with the runner's taskFailure assertion):
- wrap-failed-enter-still-runs-wrap-exit
Interception edge (nothing to replace means the hook must not fire):
- wrap-inner-env-without-on-exit-skips-exit-hook
Macro propagation beyond openjd_env (wrapped process's openjd_fail
recognized through the wrap script's forwarded stdout):
- wrap-openjd-fail-from-wrapped-process
Variable-scope rule beyond action args (env-side validation fixtures):
- 4--wrappedaction-in-cancelation-outside-hook.invalid
- 4--wrappedaction-in-embedded-file.invalid
Suite grows 59 -> 72. Current implementation status (expected, matches
the audit's open findings): openjd-rs with OpenJobDescription/openjd-rs
PR 265 passes 69/72 (fails lets-in-hooks, variables-map exclusion,
cleanup guarantee = audit F12/F9/F15); openjd-sessions-for-python's RFC
0008 branch passes 68/72 (fails the three runtime cancelation-validation
fixtures and the jobEnvironments round-trip = audit F5/F2). The
conformance CI workflows tolerate implementation failures by design.
Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>
* docs: State the wrap-hook nothing-to-replace rule explicitly
Review feedback on the wrap-inner-env-without-on-exit-skips-exit-hook
fixture: the behavior it pins — a wrap hook runs only in place of an
action the inner entity actually defines, so an inner environment with
no onExit (or no script at all) gets no onWrapEnvExit — was implicit in
the spec's "runs instead of" phrasing rather than stated.
Make it explicit in both places implementers read:
- Template Schemas: new WRAP_ACTIONS constraint 5 (nothing-to-replace
rule), including the variables:-only environment case and the note
that onWrapTaskRun always runs because every <StepScript> defines
onRun.
- How-Jobs-Are-Run: one sentence in the wrap interception paragraph.
- The fixture's header comment now cites the new constraint instead of
deriving the behavior.
The RFC document is left unchanged as the historical design record; the
wiki pages are the living specification. Conformance suite re-run:
matrix unchanged (the edited fixture passes on both implementations).
Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>
* docs: State the nothing-to-replace rule in RFC 0008 as well
Follow-up to the previous commit, which made the rule explicit in the
wiki pages: mirror it in the RFC document itself so all three spec
sources agree.
- "Wrap ordering with multiple environments" gains a normative
Nothing-to-replace rule paragraph (MUST NOT run a hook when the inner
environment defines no matching action or no script at all), with the
rationale that a hook is a replacement rather than a lifecycle
notification, and the note that onWrapTaskRun always runs because
every <StepScript> defines onRun.
- The "Modifications to How Jobs Are Run" diff block is updated to
match the sentence now present in the actual How-Jobs-Are-Run page,
keeping the RFC's quoted diff in sync with the published text.
Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>
---------
Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>"
"feat: Finalize RFC 0008 wrap-hook spec and nullable variable types
Resolve review feedback deferred at RFC 0008 merge time, on PR #148,
and on openjd-rs PR #261.
- Make the wiki authoritative: copy RFC 0008 normative content (the
WrappedAction/WrappedEnv/WrappedStep variable tables, timeout and
cancelation semantics, failure and cleanup guarantees, and stdout
macro rules) into 2023-09-Template-Schemas and How-Jobs-Are-Run,
linking the RFC for attribution only.
- Add WrappedAction.Cancelation.NotifyPeriodInSeconds (int?) so wrap
scripts can honor the wrapped action's full cancelation semantics.
- Retype WrappedAction.Timeout as int? and Cancelation.Mode as string?
— null when the wrapped action declares no timeout or <Cancelation>,
following EXPR semantics for optional data instead of 0/empty-string
sentinels. Breaking change to the Timeout contract introduced
earlier on this branch; both runtimes update in lockstep.
- Specify round-trip forwarding under FEATURE_BUNDLE_1: a wrap hook
can adopt the wrapped action's timeout and cancelation via
whole-field format strings. Declared values forward verbatim; null
drops the field (for mode, the entire cancelation object, since mode
is the required discriminator). A format-string mode otherwise
behaves like any normal format string: partial interpolation is
valid, and the resolved value must be a valid mode name at run time.
- Fix the RFC Basic Example (format-string timeouts require
FEATURE_BUNDLE_1 and 0 is out of range), correct the WRAP_ACTIONS
README timeout-sentinel bullet, and add EXPR to
wrap-partial-hooks-rejected so the missing-EXPR rule cannot mask the
all-or-nothing defect it tests.
- Conformance: add fixtures covering cancelation mode and
notify-period injection, schema-default forwarding, null sentinels
with observable coalescing assertions, the round-trip cases,
partial-interpolation mode, and invalid fixtures pinning the
FEATURE_BUNDLE_1 gating. Round-trip and null-sentinel fixtures pin
target behavior for openjd-rs 30cdf37, openjd-model-for-python
71fd0d3, and openjd-sessions-for-python 0295e21.
Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>"
"rfc: Environment Wrap Actions (#130)
* feat(RFC): Environment Wrap Actions
Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>"
"feat: Add OPENJD_SESSION_WORKING_DIR eenvironment variable to spec
Add documentation and conformance tests for the OPENJD_SESSION_WORKING_DIR
environment variable, which exposes the Session working directory to nested
subprocesses.
Documentation changes:
- New 'Session Environment Variables' section in How-Jobs-Are-Run.md with
design rationale explaining why env vars are generally avoided (tooling
parseability) and why this one is acceptable (same value as template var,
CWD already points there)
- Updated Session.WorkingDirectory description in How-Jobs-Are-Constructed.md
to reference the corresponding environment variable
Conformance tests:
- Verify OPENJD_SESSION_WORKING_DIR is set and matches Session.WorkingDirectory
- Verify the env var propagates to child processes
Signed-off-by: Sean Tang <171081544+seant-aws@users.noreply.github.com>"
feat: Merge RFC 0003 into the 2023-09 template schema wiki
Signed-off-by: Brian Axelson <86568017+baxeaz@users.noreply.github.com>
feat: Merge RFC 0001 into the 2023-09 template schema wiki (#65)
Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
fix: wiki sync failure
Signed-off-by: Daniel Neilson <53624638+ddneilson@users.noreply.github.com>
chore: tidying up specification license (#16)
Signed-off-by: Daniel Neilson <53624638+ddneilson@users.noreply.github.com>
fix: add missing information on Environment stdout messages (#11)
The blurb on stdout/stderr messages was missing information on the
openjd_env and openjd_unset_env prefixes. This remedies that.
Signed-off-by: Daniel Neilson <53624638+ddneilson@users.noreply.github.com>
docs: modify wiki for readability (#8)
Signed-off-by: Sean Wallitsch <snw@amazon.com>
feat(wiki): Refine introduction to the specification's concepts (#6)
This rearranges, and rewrites part of the introduction to Open Job Description
concepts. Notably, the pages on Job Structure, Format Strings, and Overview
have been merged in to a page on How Jobs Are Constructed.
With this change we have a concept introduction that is broken up in to two parts:
1. Job definition and injest; and
2. Running jobs.
A future addition will add a guided narrative introduction that guides the reader
through construction of a job template; starting with a simple one, and then adding
to that through the narrative. Concepts for jobs, job templates, and running jobs
will be introduced incrementally through this narrative form.
Signed-off-by: Daniel Neilson <53624638+ddneilson@users.noreply.github.com>