@8lines/gauntlet-protocol 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +265 -0
  3. package/dist/environment.d.ts +3 -0
  4. package/dist/environment.d.ts.map +1 -0
  5. package/dist/environment.js +32 -0
  6. package/dist/environment.js.map +1 -0
  7. package/dist/identifiers.d.ts +4 -0
  8. package/dist/identifiers.d.ts.map +1 -0
  9. package/dist/identifiers.js +5 -0
  10. package/dist/identifiers.js.map +1 -0
  11. package/dist/index.d.ts +8 -0
  12. package/dist/index.d.ts.map +1 -0
  13. package/dist/index.js +8 -0
  14. package/dist/index.js.map +1 -0
  15. package/dist/placements.d.ts +5 -0
  16. package/dist/placements.d.ts.map +1 -0
  17. package/dist/placements.js +99 -0
  18. package/dist/placements.js.map +1 -0
  19. package/dist/portable-pattern.d.ts +2 -0
  20. package/dist/portable-pattern.d.ts.map +1 -0
  21. package/dist/portable-pattern.js +450 -0
  22. package/dist/portable-pattern.js.map +1 -0
  23. package/dist/preset-secrets.d.ts +7 -0
  24. package/dist/preset-secrets.d.ts.map +1 -0
  25. package/dist/preset-secrets.js +694 -0
  26. package/dist/preset-secrets.js.map +1 -0
  27. package/dist/revision.d.ts +11 -0
  28. package/dist/revision.d.ts.map +1 -0
  29. package/dist/revision.js +135 -0
  30. package/dist/revision.js.map +1 -0
  31. package/dist/schema-profile.d.ts +5 -0
  32. package/dist/schema-profile.d.ts.map +1 -0
  33. package/dist/schema-profile.js +295 -0
  34. package/dist/schema-profile.js.map +1 -0
  35. package/dist/semantic-validation.d.ts +24 -0
  36. package/dist/semantic-validation.d.ts.map +1 -0
  37. package/dist/semantic-validation.js +321 -0
  38. package/dist/semantic-validation.js.map +1 -0
  39. package/dist/types.d.ts +437 -0
  40. package/dist/types.d.ts.map +1 -0
  41. package/dist/types.js +2 -0
  42. package/dist/types.js.map +1 -0
  43. package/fixtures/v1/adapter-semantic-vectors.json +3257 -0
  44. package/fixtures/v1/adapter-semantic-vectors.schema.json +519 -0
  45. package/fixtures/v1/create-run-request.valid.json +33 -0
  46. package/fixtures/v1/data-source-page.valid.json +18 -0
  47. package/fixtures/v1/data-source-query.valid.json +12 -0
  48. package/fixtures/v1/data-source-resolve-request.valid.json +10 -0
  49. package/fixtures/v1/data-source-resolve-response.valid.json +17 -0
  50. package/fixtures/v1/health.valid.json +4 -0
  51. package/fixtures/v1/jcs-revision-vectors.json +114 -0
  52. package/fixtures/v1/manifest.invalid-major-version.json +18 -0
  53. package/fixtures/v1/manifest.invalid-unknown-property.json +27 -0
  54. package/fixtures/v1/manifest.minor-forward.valid.json +142 -0
  55. package/fixtures/v1/manifest.valid.json +137 -0
  56. package/fixtures/v1/operation.invalid-remote-ref.json +28 -0
  57. package/fixtures/v1/operation.invalid-schema-profile.json +28 -0
  58. package/fixtures/v1/operation.invalid-unsafe-id.json +28 -0
  59. package/fixtures/v1/operation.valid.json +227 -0
  60. package/fixtures/v1/problem.unsupported-capability.valid.json +7 -0
  61. package/fixtures/v1/problem.valid.json +8 -0
  62. package/fixtures/v1/problem.validation.valid.json +16 -0
  63. package/fixtures/v1/run-event.valid.json +21 -0
  64. package/fixtures/v1/run.cancelled.valid.json +17 -0
  65. package/fixtures/v1/run.failed.valid.json +32 -0
  66. package/fixtures/v1/run.invalid-active-problem.json +16 -0
  67. package/fixtures/v1/run.invalid-cancelled-problem.json +17 -0
  68. package/fixtures/v1/run.invalid-terminal-without-problem.json +12 -0
  69. package/fixtures/v1/run.invalid-timed-out-status.json +18 -0
  70. package/fixtures/v1/run.queued.valid.json +15 -0
  71. package/fixtures/v1/run.succeeded.valid.json +68 -0
  72. package/fixtures/v1/run.timed-out.valid.json +18 -0
  73. package/fixtures/v1/session-launch.valid.json +5 -0
  74. package/fixtures/v1/tc-schema-core-pattern-vectors.json +450 -0
  75. package/fixtures/v1/upload-response.valid.json +11 -0
  76. package/openapi/adapter-v1.yaml +251 -0
  77. package/package.json +41 -0
  78. package/schemas/v1/common.schema.json +558 -0
  79. package/schemas/v1/create-run-request.schema.json +16 -0
  80. package/schemas/v1/data-source-page.schema.json +15 -0
  81. package/schemas/v1/data-source-query.schema.json +14 -0
  82. package/schemas/v1/data-source-resolve-request.schema.json +16 -0
  83. package/schemas/v1/data-source-resolve-response.schema.json +27 -0
  84. package/schemas/v1/health.schema.json +12 -0
  85. package/schemas/v1/manifest.schema.json +147 -0
  86. package/schemas/v1/operation-definition.schema.json +326 -0
  87. package/schemas/v1/problem.schema.json +5 -0
  88. package/schemas/v1/run-event.schema.json +15 -0
  89. package/schemas/v1/run.schema.json +95 -0
  90. package/schemas/v1/session-launch.schema.json +13 -0
  91. package/schemas/v1/upload.schema.json +11 -0
package/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
package/README.md ADDED
@@ -0,0 +1,265 @@
1
+ # Gauntlet adapter protocol
2
+
3
+ `@8lines/gauntlet-protocol` is the language-neutral contract shared by the
4
+ Gauntlet control plane and every in-application adapter. The checked-in JSON
5
+ Schemas and OpenAPI document define the wire format. This document defines the
6
+ portable behavior that JSON Schema and revision implementations must share
7
+ across TypeScript, PHP, and Java.
8
+
9
+ The executable sources of truth are:
10
+
11
+ - `fixtures/v1/tc-schema-core-pattern-vectors.json` for portable regular
12
+ expressions; and
13
+ - `fixtures/v1/jcs-revision-vectors.json` for canonical JSON and revision
14
+ hashing; and
15
+ - `fixtures/v1/adapter-semantic-vectors.json` for manifest, operation,
16
+ data-source resolve, and preset-secret semantics. Its closed companion schema
17
+ is `fixtures/v1/adapter-semantic-vectors.schema.json`.
18
+
19
+ An SDK implementation is conformant only when it accepts and rejects those
20
+ vectors exactly. It must not broaden the grammar based on features available in
21
+ its host regular-expression engine.
22
+
23
+ ## `tc-schema-core@1` patterns
24
+
25
+ Patterns use case-sensitive ECMAScript Unicode search semantics over the
26
+ `unicode-scalar-sequences` instance domain declared by the vector artifact. No
27
+ multiline, dot-all, ignore-case, global, or sticky flag is enabled. An
28
+ unanchored pattern searches within the value. `^` and `$` anchor it; `$` means
29
+ absolute end and does not match before a final LF, CR, U+2028, or U+2029. The
30
+ validated source is compiled unchanged with the equivalent of
31
+ `new RegExp(pattern, "u")` after the portable checks. Validators must not
32
+ translate or normalize it.
33
+
34
+ Candidates containing lone UTF-16 surrogate code units are outside this
35
+ instance domain. Adapter and control-plane protocol boundaries MUST reject such
36
+ strings before JSON Schema pattern evaluation; this requirement does not alter
37
+ the current wire schema shapes. ECMAScript `/u` permits a negated class to match
38
+ a lone surrogate, but that host-engine behavior does not expand the portable
39
+ domain: the candidate must already have been rejected, and portable interval
40
+ analysis complements classes only over Unicode scalar values.
41
+
42
+ A decoded pattern is limited to 512 UTF-16 code units. Its grammar is:
43
+
44
+ ```text
45
+ disjunction := alternative ("|" alternative)*
46
+ alternative := term*
47
+ term := assertion | atom quantifier?
48
+ assertion := "^" | "$"
49
+ atom := raw-scalar | allowed-escape | class | group
50
+ group := "(" ("?:")? disjunction ")"
51
+ quantifier := "?" | "*" | "+" | "{" m ("," n?)? "}"
52
+ ```
53
+
54
+ Capturing and noncapturing groups have the same matching semantics in this
55
+ profile. Quantifier bounds are canonical ASCII decimals without leading zeroes
56
+ apart from `0`, are at most 1000, and satisfy `m <= n`. Quantifiers are greedy.
57
+
58
+ Outside a class, the only escapes are literals from
59
+ `\\^$.*+?()[]{}|/`. Inside a class, the only escapes are `\\`, `\]`,
60
+ `\^`, and `\-`. Negation and raw Unicode scalar literals are supported. An
61
+ ordinary range is allowed only when it does not span the surrogate block: a
62
+ range whose start is at most U+D7FF and whose end is at least U+E000 is
63
+ rejected. A raw hyphen is a literal in the positions where ECMAScript treats it
64
+ as one, including the trailing hyphens used by the protocol ID patterns;
65
+ escaping it is preferred in newly authored patterns. Accepted range sets are
66
+ normalized to Unicode-scalar intervals.
67
+
68
+ The profile rejects:
69
+
70
+ - lone surrogates and decoded C0/C1 control characters;
71
+ - `.`, shorthand classes, boundaries, backreferences, lookaround, named groups,
72
+ inline flags, and property, code-point, hex, or control escapes;
73
+ - lazy, possessive, or repeated quantifier suffixes and malformed bounds;
74
+ - nested, empty, or wildcard-equivalent classes, descending or
75
+ surrogate-spanning ranges, and class set operators `&&` and `--`; and
76
+ - any expression that fails the deterministic analysis below.
77
+
78
+ The identical scanner is applied to every `pattern` value and every
79
+ `patternProperties` key. A rejection reports the escaped JSON Schema pointer
80
+ and a fixed portable-profile message; it never includes a `pattern` value in
81
+ the message body.
82
+
83
+ ### One-pass guarantee
84
+
85
+ Each consuming literal or class occurrence receives a distinct position and a
86
+ normalized set of Unicode-scalar intervals. While parsing, the validator
87
+ computes nullable-derivation multiplicity, `FIRST`, and `LAST` summaries.
88
+ Alternation adds nullable derivations and concatenation multiplies them; any
89
+ combinator producing more than one is rejected. A quantifier with a maximum
90
+ greater than one requires a non-nullable body and adds every
91
+ `LAST(body) -> FIRST(body)` transition. An optional quantifier also rejects a
92
+ nullable body because skipping it and taking its empty derivation are two
93
+ paths. Exact `{0}` remains one unambiguous empty derivation.
94
+
95
+ Transitions form a multiset: parallel identical transitions are not removed.
96
+ At the start and after every consuming position, all possible target character
97
+ sets must be pairwise disjoint. This rejects ambiguous expressions such as
98
+ `(a+)+`, `(a|aa)*`, `(a*)*`, and `a?a`, while accepting the deterministic JSON
99
+ Pointer expression `^(?:/(?:[^~/]|~[01])*)*$`. Combined with the 512-code-unit
100
+ limit, this defines deterministic matching from one start position.
101
+
102
+ Native search can still retry a deterministic expression at every input
103
+ position: unanchored `a*b`, for example, is quadratic when the suffix is absent.
104
+ Therefore any source containing `*`, `+`, or an open upper bound `{m,}` MUST
105
+ begin at its first code unit with an unescaped `^`, and the root expression MUST
106
+ have no top-level alternation. Alternation nested after that shared anchor is
107
+ allowed. Unanchored expressions may use only bounded quantifiers; their maximum
108
+ of 1000 bounds work per candidate start. Together these rules define the
109
+ portable linear-time profile. A broader grammar requires a new profile
110
+ identifier.
111
+
112
+ ## JCS revisions
113
+
114
+ Revision inputs are JSON parsed as IEEE-754 binary64 values. To calculate a
115
+ revision:
116
+
117
+ 1. Work on own JSON data properties only. Preserve a member literally named
118
+ `__proto__`; it has no prototype semantics.
119
+ 2. Remove only the named revision member (`revision` or `manifestRevision`) at
120
+ the document root. Retain nested members with the same name.
121
+ 3. Reject lone surrogates in both property names and string values. Reject
122
+ non-finite numbers and integer-valued unsafe binary64 numbers when their
123
+ ECMAScript JSON serialization is non-exponential. Exponential values such
124
+ as `1e21` remain accepted.
125
+ 4. Canonicalize the remaining document with RFC 8785/JCS, including UTF-16
126
+ property-name ordering and ECMAScript number serialization.
127
+ 5. Hash the UTF-8 canonical JSON bytes with SHA-256 and return lowercase
128
+ hexadecimal prefixed by `sha256:`.
129
+
130
+ The numeric boundary is intentional. In particular, `-0`, `1e-7`, `1e-6`,
131
+ `1e21`, `1e-27`, `5e-324`, `1e-320`, and
132
+ `2.2250738585072014e-308` have frozen canonical representations, while the
133
+ non-exponential unsafe integer `9007199254740992` is rejected. SDK authors
134
+ must use the canonical strings and hashes in `jcs-revision-vectors.json` rather
135
+ than recomputing expected test values with their production implementation.
136
+
137
+ ## Manifest semantics
138
+
139
+ Envelope validation against `manifest.schema.json` runs before
140
+ `manifestSemanticsAreValid`. The schema owns the closed shape of availability
141
+ Problems and diagnostics, including the portable `operationId` syntax. The
142
+ shared semantic predicate then applies these cross-document rules:
143
+
144
+ - an `available` operation summary may require only profiles and capabilities
145
+ listed by the manifest;
146
+ - an `unavailable` summary retains its complete declared requirements even
147
+ when one or more are not implemented by the adapter, and carries its safe
148
+ schema-valid Problem; and
149
+ - a diagnostic may identify a schema-valid operation ID that was omitted from
150
+ `operations` after its binding failed validation. Diagnostic identity does
151
+ not imply that an executable operation summary exists.
152
+
153
+ Feature references, summary and data-source uniqueness, content-derived
154
+ revisions, and data-source schema semantics are identical for both availability
155
+ states.
156
+
157
+ ## Execution-policy semantics
158
+
159
+ The execution policy is enforceable behavior, not presentation metadata.
160
+ `concurrency` omitted or set to `allow` admits independent handlers. `forbid`
161
+ admits no new run while another run of the same operation owns an execution
162
+ reservation and returns `urn:gauntlet:problem:operation-busy` with status
163
+ 409; an idempotent replay is still the original run and never becomes a busy
164
+ error. `queue` admits runs in reservation order and starts one handler for that
165
+ operation at a time. Queue waiting does not consume the operation timeout.
166
+
167
+ `timeoutSeconds` starts when the handler enters `running`. Expiry requests
168
+ cooperative cancellation and terminalizes the run as `timed_out` with
169
+ `urn:gauntlet:problem:run-timed-out`, title `Run timed out`, and status 504.
170
+ Explicit cancellation of a cancellable queued or running run terminalizes it
171
+ as `cancelled` with `urn:gauntlet:problem:run-cancelled`, title
172
+ `Run cancelled`, and status 409. Cancelling a run whose
173
+ operation declares `cancellationSupported: false` returns
174
+ `urn:gauntlet:problem:run-not-cancellable` with status 409 and does not
175
+ mutate the run, including when the stored run is already terminal. For an
176
+ operation that does support cancellation, retrying cancellation after a run
177
+ became terminal returns that same authoritative terminal run unchanged.
178
+
179
+ Handlers must observe their SDK's cancellation signal or cancellation check to
180
+ stop application work promptly; runtimes cannot safely hard-kill arbitrary
181
+ application code. Once cancellation or timeout wins the terminal transition,
182
+ the context is closed and late progress, artifacts, actions, handler results,
183
+ or failures cannot mutate that run. Exactly one terminal transition wins. A
184
+ serialized execution reservation remains held until the underlying handler has
185
+ actually settled, even after its run becomes terminal, so application side
186
+ effects cannot overlap. Consequently, an uncooperative handler can block later
187
+ `queue` runs (and keep `forbid` busy) until it returns.
188
+
189
+ In-memory execution coordinators are single-process test/development defaults.
190
+ An adapter deployed with multiple workers or replicas must use an
191
+ application-owned coordinator shared by those replicas together with its
192
+ shared durable `RunStore`; otherwise `forbid`, FIFO ordering, and cross-replica
193
+ cancellation are only process-local and the adapter must not claim those
194
+ guarantees.
195
+
196
+ ## Adapter semantic vectors
197
+
198
+ `adapter-semantic-vectors.json` is the normative, language-neutral v1 truth
199
+ table. Consumers verify each source fixture's raw SHA-256 before parsing it,
200
+ then evaluate the checked-in boolean; expected results and revisions must not
201
+ be calculated by the predicate under test. Every source path is a safe sibling
202
+ basename. The vector instance is ASCII UTF-8 without a BOM, uses LF only, ends
203
+ with LF, and remains below 256 KiB. The companion schema and four source
204
+ fixtures have the same UTF-8/BOM/CR/final-LF byte contract.
205
+
206
+ The `rfc6902-test-subset@1` construction profile applies ordered `add`,
207
+ `remove`, `replace`, and `copy` patches to a fresh owned-JSON clone. JSON
208
+ Pointer and RFC 6902 rules apply exactly: array indexes are canonical decimal,
209
+ `-` is only an add/copy destination, copy resolves before mutation and clones
210
+ its value, and remove/replace require an existing own member. No parent
211
+ creation, root replacement, merge, interpolation, wildcard, URI resolution, or
212
+ code execution exists. A patch cannot address the root revision member.
213
+ Manifest and operation revisions are handled afterward by the explicit
214
+ `preserve` or `set` directive, and every declared match or mismatch is checked
215
+ independently before the semantic predicate runs.
216
+
217
+ The `tc-preset-operation@1` profile clones the verified operation fixture,
218
+ uses the suite's literal object input schema, and emits one ordered secret rule
219
+ per `secretPointers` entry without deduplication. It removes `uiSchema`, sets
220
+ `dataSources` to `[]`, and creates `preset-<index>` / `Preset <index>` entries
221
+ from independently cloned inputs. An empty pointer list still produces
222
+ `inputHandling.rules: []`. The case's checked-in revision is installed and
223
+ verified before envelope and semantic evaluation. Parsed schema member order
224
+ is preserved; canonical ordering is used only for the separate revision
225
+ assertion.
226
+
227
+ ### Preset analysis ceilings
228
+
229
+ The v1 analyzer accepts counts exactly at these maxima and fails closed only
230
+ when the next graph node, edge, or visit exceeds one:
231
+
232
+ ```text
233
+ MAX_GRAPH_NODES = 250000
234
+ MAX_GRAPH_EDGES = 500000
235
+ MAX_PRESET_VISITS = 500000
236
+
237
+ inputNodeCount = roots + array elements + object-member values
238
+ visitBudget = min(500000, max(8192,
239
+ graphNodes * 4 + graphEdges * 2 + inputNodeCount * 64))
240
+ ```
241
+
242
+ Object keys do not count as input nodes. Graph nodes use canonical JSON Schema
243
+ pointers; every structural occurrence is an edge. Secret pointer strings are
244
+ deduplicated for graph compilation, while duplicate rules remain in the
245
+ operation and its revision. Route multiplicity saturates at two. The visit
246
+ counter is shared by every preset in an operation; object-identity and
247
+ schema-node primitive de-duplication sets reset for each preset.
248
+
249
+ Static traversal covers local `$ref`, `properties`, `dependentSchemas`,
250
+ `allOf`, `anyOf`, `oneOf`, `not`, `if`, `then`, `else`, `prefixItems`, and
251
+ `items`. `patternProperties`, `contains`, `additionalProperties`,
252
+ `propertyNames`, `unevaluatedItems`, `unevaluatedProperties`, and
253
+ `contentSchema` make a target dynamically addressed and therefore fail closed.
254
+
255
+ The closed `tc-preset-workloads@1` recipes are `deep-chain`,
256
+ `rules-presets-cartesian`, `dense-mutual-reference`, and `wide-array`. Their
257
+ parameters, expected revisions, and canonical full-operation UTF-8 byte counts
258
+ are portable requirements; the wide operation is generated only inside an
259
+ isolated child process and is never checked in. Node 24 reference metadata
260
+ retains 2,500 ms timeouts for cartesian and dense workloads, a 10,000 ms wide
261
+ timeout, 512 MiB old-space and 48 MiB semi-space flags, secret-wide RSS below
262
+ 458,752 KiB, and a secret/control RSS delta below 40,960 KiB. Those process
263
+ budgets are Node-specific; they do not change the portable recipes or results.
264
+
265
+ [Documentation index](../../docs/README.md)
@@ -0,0 +1,3 @@
1
+ import type { EnvironmentDescriptor } from "./types.js";
2
+ export declare function assertNonProductionEnvironment(value: unknown): EnvironmentDescriptor;
3
+ //# sourceMappingURL=environment.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAmB,MAAM,YAAY,CAAC;AAWzE,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAmBpF"}
@@ -0,0 +1,32 @@
1
+ import { isProtocolId } from "./identifiers.js";
2
+ import { assertRuntimeJsonData } from "./revision.js";
3
+ const KINDS = new Set([
4
+ "development", "test", "qa", "staging", "uat", "preview", "sandbox",
5
+ ]);
6
+ const PRODUCTION_TOKEN = /(^|[._:-])(prod|production|live)($|[._:-])/i;
7
+ function invalidEnvironment() {
8
+ return new TypeError("Invalid non-production environment descriptor");
9
+ }
10
+ export function assertNonProductionEnvironment(value) {
11
+ try {
12
+ assertRuntimeJsonData(value);
13
+ if (value === null || typeof value !== "object" || Array.isArray(value))
14
+ throw invalidEnvironment();
15
+ const keys = Object.keys(value);
16
+ if (keys.length !== 2 || !Object.hasOwn(value, "name") || !Object.hasOwn(value, "kind")) {
17
+ throw invalidEnvironment();
18
+ }
19
+ const record = value;
20
+ if (!isProtocolId(record.name)
21
+ || PRODUCTION_TOKEN.test(record.name)
22
+ || typeof record.kind !== "string"
23
+ || !KINDS.has(record.kind)) {
24
+ throw invalidEnvironment();
25
+ }
26
+ return Object.freeze({ name: record.name, kind: record.kind });
27
+ }
28
+ catch {
29
+ throw invalidEnvironment();
30
+ }
31
+ }
32
+ //# sourceMappingURL=environment.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGtD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAkB;IACrC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS;CACpE,CAAC,CAAC;AACH,MAAM,gBAAgB,GAAG,6CAA6C,CAAC;AAEvE,SAAS,kBAAkB;IACzB,OAAO,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,KAAc;IAC3D,IAAI,CAAC;QACH,qBAAqB,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,MAAM,kBAAkB,EAAE,CAAC;QACpG,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;YACxF,MAAM,kBAAkB,EAAE,CAAC;QAC7B,CAAC;QACD,MAAM,MAAM,GAAG,KAA0C,CAAC;QAC1D,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC;eACzB,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;eAClC,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;eAC/B,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAuB,CAAC,EAAE,CAAC;YAChD,MAAM,kBAAkB,EAAE,CAAC;QAC7B,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAuB,EAAE,CAAC,CAAC;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,kBAAkB,EAAE,CAAC;IAC7B,CAAC;AACH,CAAC"}
@@ -0,0 +1,4 @@
1
+ import type { ProtocolId } from "./types.js";
2
+ export declare const PROTOCOL_ID_PATTERN: RegExp;
3
+ export declare function isProtocolId(value: unknown): value is ProtocolId;
4
+ //# sourceMappingURL=identifiers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../src/identifiers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,eAAO,MAAM,mBAAmB,QAAwC,CAAC;AAEzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE"}
@@ -0,0 +1,5 @@
1
+ export const PROTOCOL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
2
+ export function isProtocolId(value) {
3
+ return typeof value === "string" && PROTOCOL_ID_PATTERN.test(value);
4
+ }
5
+ //# sourceMappingURL=identifiers.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"identifiers.js","sourceRoot":"","sources":["../src/identifiers.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,mBAAmB,GAAG,qCAAqC,CAAC;AAEzE,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC"}
@@ -0,0 +1,8 @@
1
+ export * from "./identifiers.js";
2
+ export * from "./environment.js";
3
+ export * from "./placements.js";
4
+ export * from "./revision.js";
5
+ export * from "./schema-profile.js";
6
+ export * from "./semantic-validation.js";
7
+ export * from "./types.js";
8
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,8 @@
1
+ export * from "./identifiers.js";
2
+ export * from "./environment.js";
3
+ export * from "./placements.js";
4
+ export * from "./revision.js";
5
+ export * from "./schema-profile.js";
6
+ export * from "./semantic-validation.js";
7
+ export * from "./types.js";
8
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC"}
@@ -0,0 +1,5 @@
1
+ import type { JsonPointer, OperationDefinition } from "./types.js";
2
+ export declare const PAGE_PLACEMENTS_PROFILE = "gauntlet-page-placements@1";
3
+ export declare function placementSchemaPointer(inputPointer: JsonPointer): JsonPointer | undefined;
4
+ export declare function operationPlacementsAreValid(operation: Pick<OperationDefinition, "inputSchema" | "inputHandling" | "placements">): boolean;
5
+ //# sourceMappingURL=placements.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"placements.d.ts","sourceRoot":"","sources":["../src/placements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEnE,eAAO,MAAM,uBAAuB,+BAA+B,CAAC;AAkBpE,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,WAAW,GAAG,WAAW,GAAG,SAAS,CAKzF;AAmDD,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,IAAI,CAAC,mBAAmB,EAAE,aAAa,GAAG,eAAe,GAAG,YAAY,CAAC,GACnF,OAAO,CAqBT"}