@unbrained/pm-http 0.0.0-stage → 2026.11.19

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 (47) hide show
  1. package/ARCHITECTURE.md +59 -0
  2. package/CHANGELOG.md +29 -0
  3. package/LICENSE +21 -0
  4. package/README.md +186 -2
  5. package/dist/index.d.ts +116 -0
  6. package/dist/index.d.ts.map +1 -0
  7. package/dist/index.js +30 -0
  8. package/dist/index.js.map +1 -0
  9. package/dist/src/api.d.ts +56 -0
  10. package/dist/src/api.d.ts.map +1 -0
  11. package/dist/src/api.js +200 -0
  12. package/dist/src/api.js.map +1 -0
  13. package/dist/src/capture.d.ts +23 -0
  14. package/dist/src/capture.d.ts.map +1 -0
  15. package/dist/src/capture.js +113 -0
  16. package/dist/src/capture.js.map +1 -0
  17. package/dist/src/commands.d.ts +6 -0
  18. package/dist/src/commands.d.ts.map +1 -0
  19. package/dist/src/commands.js +84 -0
  20. package/dist/src/commands.js.map +1 -0
  21. package/dist/src/core.d.ts +36 -0
  22. package/dist/src/core.d.ts.map +1 -0
  23. package/dist/src/core.js +75 -0
  24. package/dist/src/core.js.map +1 -0
  25. package/dist/src/derive.d.ts +62 -0
  26. package/dist/src/derive.d.ts.map +1 -0
  27. package/dist/src/derive.js +139 -0
  28. package/dist/src/derive.js.map +1 -0
  29. package/dist/src/policy.d.ts +29 -0
  30. package/dist/src/policy.d.ts.map +1 -0
  31. package/dist/src/policy.js +137 -0
  32. package/dist/src/policy.js.map +1 -0
  33. package/dist/src/store.d.ts +42 -0
  34. package/dist/src/store.d.ts.map +1 -0
  35. package/dist/src/store.js +124 -0
  36. package/dist/src/store.js.map +1 -0
  37. package/dist/src/transport.d.ts +9 -0
  38. package/dist/src/transport.d.ts.map +1 -0
  39. package/dist/src/transport.js +144 -0
  40. package/dist/src/transport.js.map +1 -0
  41. package/dist/src/types.d.ts +140 -0
  42. package/dist/src/types.d.ts.map +1 -0
  43. package/dist/src/types.js +2 -0
  44. package/dist/src/types.js.map +1 -0
  45. package/docs/real-data.md +20 -0
  46. package/manifest.json +14 -0
  47. package/package.json +150 -4
@@ -0,0 +1,59 @@
1
+ # Architecture
2
+
3
+ ## Records and SDK ownership
4
+
5
+ An existing task owns the registered string field `http_state`. Its version-1 envelope contains a monotonic revision, immutable probes, replaceable explicit contracts, append-only observations and per-operation send plans. Native SDK history records every state transition. Task comments record declarations, reviews, contracts and completed or refused sends; pre-effect plan/sending transitions add no task comment. Declarations also add their secret-free URL templates as native SDK source links in the same conditional mutation; existing link notes survive. Links are references and execute no requests. Task identity, settings/author selection, schema registration, complete field reads, item locks and conditional mutation transactions use the public pm SDK. No package-owned generic store or direct tracker-file writer exists. Native task links and context collections remain available through pm; declarations and evidence travel with the task field and its audited history.
6
+
7
+ `Store.change` takes an SDK lease for cooperating package writers, reads the current native target, compares any expected revision, and writes only `http_state` plus an optional attributable comment through `commitItemMutations`. Keyed selection uses the full prior envelope, or the initial native `updated_at`. Other native fields survive updates. Package revisions only increase. A no-op is returned only after re-reading the current target. The canonical task identity binds send-operation locks.
8
+
9
+ The pinned SDK has no atomic item expected-revision precondition ([#1576](https://github.com/unbraind/pm-cli/issues/1576)); its workspace transaction lock does not exclude ordinary native writers ([#1620](https://github.com/unbraind/pm-cli/issues/1620)). These helpers therefore do not establish linearizable compare-and-set against arbitrary native writes. Guarded send plans retain the caller's original revision, the next revision expected after this operation's own journal write, and an operation-bound digest of all native task content and complete comments, excluding only `http_state`, `updated_at` and derived collection counts. No comment text, prefix or author label establishes ownership or grants a guard exemption. Pre-effect journal transitions add no task comments, so no exclusion is necessary. Guarded planned operations created with the former weak fingerprint remain readable through all evidence APIs but refuse preview/send with `stale_revision`; explicitly create a new operation to admit current context. Checkpoints bind the invocation's original policy to known phase offsets and verify the journal identity, lifecycle and guard tuple. Erasing or rebasing metadata cannot downgrade enforcement. Cancellation preserves completed or reassigned native evidence. Before plan admission and immediately before capture, the package re-reads the probe/item and refuses changed targets with conflict reason `stale_revision`. Planned recovery retains those guards even when the resumed caller omits them. Recorded operation replay causes no network effect. A nonzero re-read-to-send window remains, including request planning, DNS and socket setup; an ordinary native writer can race it. Closing that window requires the SDK capability rather than a package lease claim.
10
+
11
+ Readers request full native items with explicit unbounded output controls. This preserves saved HTTP state even if its schema-registry entry was removed. Task and revision validation precede schema writes. Public list/observation/comparison/missing APIs return source-completeness receipts. A bounded packet distinguishes a complete source read from omitted presentation rows.
12
+
13
+ ## Send journal and recovery
14
+
15
+ Each explicit send uses a stable operation ID. Its declaration digest includes method, URL template, environment reference names, body reference, boundary, ceilings, selected headers and any reviewed capability. The journal stages are `planned`, `sending`, `received`, `recorded`, or `cancelled`. A per-operation SDK lease prevents two callers from executing the same send concurrently. Different operations can send concurrently; every recording step merges against the freshly read task revision.
16
+
17
+ The plan is durable before any request effect. Each pending send reserves 128 KiB and an observation slot before any method executes; preview and apply share admission. All package mutations account for every pending reservation, so another probe, contract or send cannot consume space promised to an in-flight result. Structural output is globally limited to 256 nodes (iteration stops at exhaustion), selected header allocation is bounded by the 16 KiB parser, and scalar response values are discarded. The resulting record fits within 64 KiB; the reservation also covers journal transition overhead. One KiB of the reservation covers the sending transition; pending transitions also reserve safe-integer revision headroom. State size is measured in serialized UTF-8 bytes. These reservations protect cooperating package writers; arbitrary native writes can ignore them, which is another consequence of the missing SDK exclusion/precondition.
18
+
19
+ Marking `sending` is durable before opening the request. The complete secret-free response replaces its reservation in the journal before observation admission. The final state mutation appends one observation, marks the plan recorded and removes the redundant journal result. Rerunning a recorded operation returns its current stored observation. A received operation completes recording. A sending operation interrupted before its result became durable converges to an explicit uncertain observation, with no resend. Cancelled/refused operations retain their audit record and release their reservation without producing a partial observation. A new request always requires a new explicit operation identity. No methods receive automatic retries.
20
+
21
+ Recovery never trusts an earlier plan over current sources: the probe digest and current target revision are revalidated on every journal step, including unchanged paths. Editing a declaration/review after planning refuses with a conflict. A stable operation ID cannot be reassigned to a different declaration. Eight public boundaries (`validated`, `plan-ready`, `planned`, `sending`, `received`, `record-ready`, `recorded`, `complete`) drive independent competing-write and crash schedules. The tests also inject a real native SDK write after transaction preparation to prove the conditional mutation refuses a changed target.
22
+
23
+ The SDK's own one-item transaction is the atomic domain-write boundary; its journals and locks are runtime state. Historical native audit entries are never removed or rewritten. A crash while a possible request is in flight can lose the response, but cannot justify guessing that the request failed or resending an uncertain mutation.
24
+
25
+ ## Redaction and structural admission
26
+
27
+ The package does not attempt to classify arbitrary response prose as safe. It discards all scalar body values and hashes every JSON property name. Arrays retain unique structural item shapes. Structural capture is bounded by breadth, depth and node ceilings and reports omissions. Contracts compile the same property-name hash representation, allowing required-field/type comparisons without retaining names or response values. SHA-256 response digests identify complete bytes or explicitly labeled captured prefixes; digests are not raw response archives.
28
+
29
+ Request header values are fixed safe MIME/User-Agent literals or `@ENV_NAME`. Query values, opaque path identifiers and request bodies are environment references. References resolve only at send time; ephemeral values never enter SDK mutation arguments, journals, history, output or diagnostics. Body references may contain arbitrary bytes represented as a process string, bounded to 1 MiB; path references must resolve to one safe identifier segment. No credential file is read and no environment is enumerated. Dry-run uses the same request planner with resolution disabled.
30
+
31
+ Header capture emits only selected names within the count ceiling. Displayed Content-Type is normalized to a fixed MIME set; a separate bounded classifier recognizes `application/json` and every syntactically valid `application/*+json` media type, case-insensitively and without retaining arbitrary subtype tokens or parameters. Structural parsing therefore does not depend on the display allowlist or selected output headers. Content-Length/Retry-After accept bounded canonical integers; Cache-Control accepts a narrow fixed grammar. All other values are redacted, including Set-Cookie, authorization-like and opaque token-shaped headers. Explicit credential echoes and controls are redacted before normalization. The receipt counts redacted captured headers and headers omitted beyond the ceiling; unselected headers also retain no value. Raw response strings never enter diagnostics. Renderers recursively escape controls, ANSI bytes, backticks and instruction delimiters, including object keys.
32
+
33
+ This is data minimization, not a promise that a digest cannot be correlated with a guessed value. Operators must put credentials in references and keep review reasons and static declarations free of secrets. No body excerpt facility exists.
34
+
35
+ ## Destination and transport rules
36
+
37
+ The boundary fixes HTTP(S) scheme, canonical host, effective port and a static path-prefix segment. Every request and redirect checks the same boundary function before DNS or socket effects. `/api` includes `/api/child`, never `/apievil`. URL parsing rejects userinfo, fragments, percent-encoded/ambiguous paths and backslashes; canonical dot-segment normalization happens before confinement. A refusing redirect receipt identifies the hop number and target digest, never a raw secret-bearing Location. Mutating redirects refuse instead of changing method or resending a body.
38
+
39
+ Each hop resolves DNS, validates every answer and pins an admitted address into the actual request lookup. Public hostnames cannot authorize private results. A boundary explicitly naming a literal private address or localhost permits that declared private destination. Origin confinement prevents credential forwarding to another origin. IPv4 normalization and conservative IPv6/reserved-range classification close alternate loopback representations. HTTPS certificate verification stays enabled. No proxy environment, cookie jar, browser state or implicit authentication is used.
40
+
41
+ The HTTP and HTTPS request promise shares one settlement state across response completion, request/response errors, aborted or prematurely closed responses, request close without a response, absolute deadline and caller cancellation. Ordinary response streams retain the existing byte/header limits. A 101 response, protocol upgrade or CONNECT handoff destroys its transport and terminates as conservative uncertainty; headers and non-HTTP payloads never enter observations. Bun can report the structured UnrequestedUpgrade error instead of those events; only its code is normalized, never its raw message. Abort listeners are removed on settlement, while error handlers absorb late transport events. CONNECT declarations remain refused by the common request policy. Available timing phases survive terminal uncertainty.
42
+
43
+ One AbortController bounds the full request lifecycle, including DNS waits, all redirect bodies, connect/TLS and final response. A caller AbortSignal/SIGINT produces a typed cancellation and no partial observation. Transport failure/timeout produces an uncertain historical outcome with a zero-retry receipt. Byte truncation closes the stream promptly and labels digest scope. Header parsing has a 16 KiB allocation ceiling; count processing is separately capped with an exact omitted-header count for parsed responses. Header-parser overflow becomes uncertainty rather than a fabricated complete response. No decompression is performed.
44
+
45
+ DNS/connect/TLS/first-byte timings are included when available, measured cumulatively from request start in milliseconds; total time is numeric when measured and null when interrupted-send recovery cannot measure it. Missing phases are absent rather than invented zeros. Observation timestamps are recorded when the result is captured; recovered interrupted-send uncertainty is timestamped at recovery and explicitly names its uncertainty. Timings and status are historical evidence.
46
+
47
+ ## Comparison and difference algorithm
48
+
49
+ Contracts define status alternatives, required selected headers (redacted values still prove presence), optional structural JSON requirements and a total latency ceiling. Properties are required recursively, extra properties are accepted, and all array items must match. The supported shape grammar excludes arbitrary JSON Schema expressions or executable validation. A changed probe digest, missing contract or uncertain outcome yields `unknown`. Incomplete captures cannot satisfy a contract, but a known bad status, excessive latency or fully captured mismatch still proves a violation. Complete response violations identify status, header, JSON shape and latency reasons. None of these verdicts imply present availability.
50
+
51
+ For each probe, observations sort by timestamp and stable ID. Find the first contract violation and its preceding last satisfying observation. If no violation exists, compare the latest pair; absent predecessors remain explicit null identities. Compare status, outcome, body digest/length, total timing, retry receipts, selected headers and each structural shape field. Include source observation IDs/timestamps, verdict reasons and exact per-field differences. Unknown evidence never becomes last-good evidence. Independent missing rows identify each absent observation, contract or complete capture.
52
+
53
+ The packet prioritizes missing-evidence rows, then deterministic per-probe difference rows. The SDK `fitOutputEnvelope` owns whole-envelope convergence, work ceilings and row admission with `policy: 'skip'`; the package supplies its inert JSON/TOON renderers including the final newline. `bytes.json` and `bytes.toon` report exact self-inclusive UTF-8 lengths; `output_fit.output_bytes` is their maximum. To populate both lengths without another fixed-point loop, envelope construction subtracts each format's length difference from the SDK maximum. The accounting fields are scalar integers spelled identically in both formats, so that difference is invariant under their digit widths. The SDK converges and verifies the final maximum including all domain and SDK receipts. Its canonical default estimator gives `estimatedTokens = ceil(max(bytes.json,bytes.toon)/4)`, retained as a compatibility field and explicitly labeled heuristic units. This is no model-token measurement or upper-bound guarantee. Rows that do not fit are omitted; receipts state exact omitted/returned counts and commands to restore the full diff or missing-evidence list. Source reads remain complete. Typed infeasible, unstable and work-limit refusals produce no partially certified packet.
54
+
55
+ ## Limits and backend boundary
56
+
57
+ Defaults and hard ceilings are documented in the README and validated before effects. Task envelopes cap operations and observations at 128, probes at 32 and serialized state at 1 MiB. Shape work, contract-file size, request/response bytes, header count/parser bytes, redirects, wall time and packet cost all have independent bounds. Synthetic fixtures contain no hosted user data. The ten-request measurement deletes its scratch tracker and stores only aggregate numbers and public endpoint descriptions.
58
+
59
+ Everything works without git. Injected native clients support other backends for reads. Current public `CommitItemMutationsOptions` and `CommitWorkspaceTransactionOptions` both require `pmRoot: string`; `ExtensionCommandSdk` does not expose a backend-owned conditional writer. [Open upstream #1399](https://github.com/unbraind/pm-cli/issues/1399) owns that capability. The package refuses remote writes and sends before schema, journal or network effects instead of claiming remote mutation conformance.
package/CHANGELOG.md ADDED
@@ -0,0 +1,29 @@
1
+ # Changelog
2
+
3
+ ## 2026.11.19 - 2026-11-19
4
+
5
+ ### Added
6
+
7
+ - Capture secret-free historical observations ([pm-http-elyh](https://github.com/unbraind/pm-http/blob/main/.agents/pm/features/pm-http-elyh.toon))
8
+ - Compare bounded response contracts ([pm-http-biny](https://github.com/unbraind/pm-http/blob/main/.agents/pm/features/pm-http-biny.toon))
9
+ - Declare bounded probes and separate mutation review ([pm-http-zuc2](https://github.com/unbraind/pm-http/blob/main/.agents/pm/features/pm-http-zuc2.toon))
10
+ - Enforce HTTP investigation safety ([pm-http-cjef](https://github.com/unbraind/pm-http/blob/main/.agents/pm/features/pm-http-cjef.toon))
11
+ - Produce bounded difference packets and missing evidence ([pm-http-s2xn](https://github.com/unbraind/pm-http/blob/main/.agents/pm/features/pm-http-s2xn.toon))
12
+ - Recover concurrent journaled sends ([pm-http-95t1](https://github.com/unbraind/pm-http/blob/main/.agents/pm/features/pm-http-95t1.toon))
13
+
14
+ ### Fixed
15
+
16
+ - Keep sync changelog regeneration consistent with the release gate ([pm-http-sync-changelog](https://github.com/unbraind/pm-http/blob/main/.agents/pm/issues/pm-http-sync-changelog.toon))
17
+ - Distinguish exact serialized byte costs from heuristic token estimates in difference packets ([pm-http-33ck](https://github.com/unbraind/pm-http/blob/main/.agents/pm/issues/pm-http-33ck.toon))
18
+
19
+ ### Other
20
+
21
+ - Close delivered items and return idle in-progress items to open (2026-11-14 sweep) ([pm-http-sweep-1114](https://github.com/unbraind/pm-http/blob/main/.agents/pm/chores/pm-http-sweep-1114.toon))
22
+ - Build task-scoped HTTP investigation context ([pm-http-76jn](https://github.com/unbraind/pm-http/blob/main/.agents/pm/epics/pm-http-76jn.toon))
23
+ - Standardize the release gate on owner approval with a daily release schedule ([pm-http-0wf8](https://github.com/unbraind/pm-http/blob/main/.agents/pm/tasks/pm-http-0wf8.toon))
24
+ - Publish pm-http as @unbrained/pm-http ([pm-http-scoped-npm-name](https://github.com/unbraind/pm-http/blob/main/.agents/pm/chores/pm-http-scoped-npm-name.toon))
25
+ - Split quick PR checks from exhaustive ARM64 deep CI ([pm-http-ci-v2](https://github.com/unbraind/pm-http/blob/main/.agents/pm/tasks/pm-http-ci-v2.toon))
26
+
27
+ ### Closed
28
+
29
+ - Closed: Expose exact packet byte costs and distinguish heuristic units from tokenizer counts ([pm-http-github-3c83aae34e57-5](https://github.com/unbraind/pm-http/blob/main/.agents/pm/issues/pm-http-github-3c83aae34e57-5.toon))
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 unbraind
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,187 @@
1
- # Temporary Holding Version
1
+ # pm-http
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Keep an HTTP investigation as task context: what request was explicitly declared, what was observed **at a recorded time**, which response contract it met, what changed, and what evidence is still missing. A resumed agent gets a compact difference packet instead of a transcript of raw responses.
4
+
5
+ `pm-http` is a TypeScript [pm](https://github.com/unbraind/pm-cli) SDK extension. It sends requests only when explicitly asked. New package under local review; releases remain disabled until the maintainer approves.
6
+
7
+ ## Install
8
+
9
+ The npm package is `@unbrained/pm-http`. Manifest identity and catalog display name remain `pm-http`; existing `pm http` commands do not change. The homepage remains <https://github.com/unbraind/pm-http#readme>.
10
+
11
+ Requires Node 22.18+ or Bun and pm 2026.10.28+. The packed consumer host is pinned to 2026.10.28. Registry commands become available after the first approved release. With a host already installed and a tracker initialized:
12
+
13
+ ```sh
14
+ pm install npm:@unbrained/pm-http
15
+ # Equivalent current spelling:
16
+ pm package install npm:@unbrained/pm-http
17
+ ```
18
+
19
+ The `npm:` prefix selects the registry. Bare `pm install @unbrained/pm-http` is interpreted as a local source by the pinned host. Package-manager installation alone does not activate the extension.
20
+
21
+ For separate fresh npm and Bun projects outside any Git repository:
22
+
23
+ ```sh
24
+ npm install --save-dev @unbrained/pm-cli@2026.10.28 @unbrained/pm-http
25
+ npx --no-install pm init http-consumer --defaults --agent-guidance skip
26
+ npx --no-install pm package install ./node_modules/@unbrained/pm-http
27
+ npx --no-install pm http probe list task-id
28
+
29
+ bun add --dev @unbrained/pm-cli@2026.10.28 @unbrained/pm-http
30
+ bunx --bun --no-install pm init http-consumer --defaults --agent-guidance skip
31
+ bunx --bun --no-install pm package install ./node_modules/@unbrained/pm-http
32
+ bunx --bun --no-install pm http probe list task-id
33
+ ```
34
+
35
+ Replace `task-id` with an existing item ID. Global SDK installation is also available after publication:
36
+
37
+ ```sh
38
+ npm i -g @unbrained/pm-http
39
+ bun add -g @unbrained/pm-http
40
+ ```
41
+
42
+ This extension has no standalone executable: `npx @unbrained/pm-http` and `bunx @unbrained/pm-http` cannot run it directly. Invoke the pm host in an initialized tracker instead:
43
+
44
+ ```sh
45
+ npx --package @unbrained/pm-cli pm install npm:@unbrained/pm-http
46
+ bunx --bun --package @unbrained/pm-cli pm install npm:@unbrained/pm-http
47
+ ```
48
+
49
+ For review before publication, run `npm ci`, `npm run build`, and `npm pack` in the package checkout. Copy `unbrained-pm-http-2026.10.29.tgz` into a fresh directory outside any Git repository, then run:
50
+
51
+ ```sh
52
+ npm install ./unbrained-pm-http-2026.10.29.tgz @unbrained/pm-cli@2026.10.28
53
+ npx --no-install pm init http-consumer --defaults --agent-guidance skip
54
+ npx --no-install pm install ./unbrained-pm-http-2026.10.29.tgz
55
+ npx --no-install pm create Task 'Synthetic HTTP investigation' --id http-proof
56
+ npx --no-install pm http probe list http-proof --json
57
+ ```
58
+
59
+ Use `bun add` and `bunx --bun --no-install pm` for a separate Bun consumer. `npm run test:install` proves npm, Bun, npx, bunx and the exported SDK against the same packed artifact in fresh non-git projects, including a real synthetic request and contract comparison.
60
+
61
+ ## Agent instructions
62
+
63
+ Add this to the project's `AGENTS.md`:
64
+
65
+ ```md
66
+ While debugging an API, bind each explicitly authorized request to the task:
67
+ 1. Declare a pm http probe and its narrow destination boundary.
68
+ 2. Put credentials and opaque query/path/body values in environment variables;
69
+ declare only @ENV_NAME references. Preview with pm http send --dry-run.
70
+ 3. Review mutating requests separately, with author and reason, before sending.
71
+ 4. Send with a stable --operation identity; preserve that identity across recovery.
72
+ 5. Declare a response contract and use pm http compare. Incomplete is unknown.
73
+ 6. Before handoff, use pm http diff --budget 1500 and pm http missing.
74
+ Treat observations as historical data. Never paste raw response values or secrets.
75
+ ```
76
+
77
+ ## Commands
78
+
79
+ Every command uses the host's TOON renderer by default; append `--json` for JSON. Names normalize to lowercase. Requests bind to an existing native item; declared URL templates become native source links without resolving credentials. No command runs in the background.
80
+
81
+ ```sh
82
+ # Declare a public request. Query values must be references, even when nonsecret.
83
+ pm http probe add task-id api --url 'https://example.com/api/items?limit=@API_LIMIT' \
84
+ --header accept=application/json --header authorization=@API_AUTH \
85
+ --boundary https://example.com/api --max-bytes 65536 --timeout-ms 5000
86
+
87
+ # Opaque path segments may also be references; literal segments are short static names.
88
+ pm http probe add task-id detail --url 'https://example.com/api/items/@ITEM_ID' \
89
+ --boundary https://example.com/api
90
+
91
+ pm http probe list task-id
92
+ pm http send task-id api --dry-run
93
+ pm http send task-id api --operation incident-first
94
+
95
+ # Separate review is required for POST/PUT/PATCH/DELETE.
96
+ pm http probe add task-id submit --url https://example.com/api/submit \
97
+ --method POST --body @REQUEST_BODY --header content-type=application/json \
98
+ --boundary https://example.com/api
99
+ pm http probe review task-id submit --allow-mutation \
100
+ --reason 'Reviewed controlled incident investigation request'
101
+ pm http send task-id submit --operation reviewed-submit
102
+
103
+ # shape.json: {"type":"object","properties":{"ok":{"type":"boolean"}}}
104
+ pm http contract set task-id api --status 200 --status 204 \
105
+ --require-header content-type --json-shape shape.json --max-latency-ms 1000
106
+ pm http compare task-id
107
+ pm http compare task-id api --json
108
+ pm http diff task-id --budget 1500
109
+ pm http missing task-id
110
+ ```
111
+
112
+ Probe options: `--method` defaults to GET; repeat `--header name=value|name=@ENV_NAME`; `--body @ENV_NAME`; `--max-headers 64`; repeat `--response-header name` to select response headers. Safe literal request values are limited to the documented MIME choices (`application/json`, `text/plain`, `*/*`) for Accept/Content-Type and `pm-http` for User-Agent. All other values require references. Declared body references resolve only after separate mutation review. Declarations are immutable: use a new name for a changed request. Review reasons are short plain prose, without credential values.
113
+
114
+ `--expected-revision N` guards declarations, reviews, contracts and the initial send plan. Subsequent journal steps re-read the current target and merge cooperating package writes through SDK mutations. `--operation` is a caller-owned idempotency identity for a send. Omit it only for a deliberately new send; a new invocation then gets a new identity. Never reuse an identity for a different probe. There is no automatic retry, including for GET.
115
+
116
+ Preview reports request intent in `willSend`; recovery and completed operations need no new request. Guarded sends retain the original caller revision through planned recovery and re-read the native task/probe immediately before capture. Every native comment participates in the context fingerprint, including comments bearing this operation's prefix or author. Pre-effect state transitions are audited by SDK history without adding task comments. Legacy guarded plans created with the former comment-filtering fingerprint remain readable but refuse preview/send; use a new explicit operation to admit current context. Changed context refuses with conflict reason `stale_revision` and exit 3. Resume with the original revision or omit it to retain the stored guard; changing that guard requires a new operation. The pinned SDK lacks an atomic item revision precondition and exclusion of ordinary writers ([#1576](https://github.com/unbraind/pm-cli/issues/1576), [#1620](https://github.com/unbraind/pm-cli/issues/1620)), so a re-read-to-send window remains during request planning, DNS and socket setup.
117
+
118
+ Every method reserves 128 KiB of task capacity and one observation slot before sending. Other package writes preserve pending reservations. Insufficient space refuses with `capacity` before network effects; use a new investigation task. `--dry-run` uses the same revision and capacity admission without writing. Arbitrary native writes can bypass package reservations until the SDK supplies the missing exclusion. JSON structure is captured for `application/json` and valid `application/*+json` types even when the opaque media subtype is redacted or Content-Type is unselected.
119
+
120
+ Contracts support statuses, required selected headers, maximum total latency and a bounded JSON structural subset: `type`, `properties` and `items`. Supported types are object, array, string, number, boolean and null. Every declared property is required; additional response properties are allowed. Array items must all match the declared item shape. Shape files are capped at 16 KiB. Unsupported schema keywords refuse before writes. A selected redacted header proves presence. An unselected required header yields unknown; an absent selected required header violates the contract. Incomplete captures yield `unknown` unless an observed constraint already proves a violation; uncertain transport outcomes remain unknown.
121
+
122
+ ## SDK
123
+
124
+ All functions take the existing item ID and explicit options. They perform no git subprocesses. Imports have no network side effects. Public failures are `HttpError` with `code`, `message`, `remedy` and safe `details`; raw transport/SDK diagnostics never cross the boundary.
125
+
126
+ ```ts
127
+ import {
128
+ addProbe, reviewProbe, listProbes, preview, send, setContract,
129
+ observations, compare, differencePacket, missingEvidence, HttpError,
130
+ } from '@unbrained/pm-http';
131
+
132
+ const options = { workspace: pmRoot, author: 'investigator' };
133
+ await addProbe(itemId, 'api', {
134
+ url: 'https://example.com/api', boundary: 'https://example.com/api',
135
+ }, options);
136
+ await setContract(itemId, 'api', { statuses: [200] }, options);
137
+ await send(itemId, 'api', { ...options, operationId: 'incident-first' });
138
+ const evidence = await observations(itemId, options);
139
+ const verdicts = await compare(itemId, { ...options, probe: 'api' });
140
+ const packet = await differencePacket(itemId, { ...options, budget: 1500 });
141
+ const missing = await missingEvidence(itemId, options);
142
+ ```
143
+
144
+ `observations(item, options)` returns complete stored observations and a completeness receipt. `compare(item, {...options, probe?})` returns historical verdicts and reasons. `differencePacket(item, {...options, budget?})` returns a self-accounted bounded packet with exact `bytes.json` and `bytes.toon` UTF-8 counts, including the final newline, all receipts, and the byte counts themselves. The SDK `output_fit` receipt records the maximum byte cost and retained source indices. Omitted-row counts and commands restore full context. `missingEvidence(item, options)` names each missing observation, contract or complete response. `listProbes`, `preview`, `reviewProbe` and the input/record interfaces are also exported. `Options` supports an injected native `PmClient`, an AbortSignal, expected revision, stable operation ID, protocol-boundary and SDK transition observers.
145
+
146
+ ## Safety and limits
147
+
148
+ - GET, HEAD and OPTIONS need no mutation capability. POST, PUT, PATCH and DELETE require separately recorded review. Mutating redirects refuse; an uncertain write is never resent automatically. Recover using the same operation ID to get the stored result or conservative uncertainty, then review any new operation yourself.
149
+ - Every redirect must retain scheme, canonical host, port and path-prefix segment. Credentials never cross origins. Five redirects maximum. Error receipts name the refused hop and a destination digest, avoiding secret-bearing Location text. HTTP(S) only; no URL userinfo, fragments, encoded path ambiguities or arbitrary literal query values.
150
+ - DNS answers are validated and pinned into the actual socket lookup for every hop. Private, loopback, link-local and other reserved destinations refuse by default. An explicit boundary naming a literal private address or `localhost` authorizes it. Fixtures use explicit loopback boundaries. Public hostnames resolving to private addresses still refuse.
151
+ - Protocol upgrades (including 101 Switching Protocols) and tunnel handoffs are outside HTTP capture. They close immediately and record conservative uncertainty with no automatic retry; no upgraded payload or header values are retained. Deadlines and cancellation settle every request/response phase and release the send lease. CONNECT declarations remain unsupported.
152
+ - Capture defaults: 64 KiB body, 64 headers, 5 seconds total across DNS, connection, TLS, body and redirects. Hard ceilings: 1 MiB body/request body, 128 response headers, 16 KiB parser headers, 60 seconds total. Caps produce capture omissions or uncertainty. No body decompression. Cancellation through SIGINT/AbortSignal leaves no partial observation; a cancelled operation requires a new explicit identity.
153
+ - Response scalar values, text and property names are never stored. JSON properties use SHA-256 identities; only structural types remain. Headers retain a narrow set of canonical nonopaque semantics. Set-Cookie, authorization-like, arbitrary/token-shaped values and known credential echoes are redacted. Other headers retain no opaque values. Digests cover captured bytes and explicitly identify prefix truncation.
154
+ - Shape admission examines at most 64 properties/items per level, 256 structural nodes, and 12 levels. Omissions never count as a satisfied contract. Response controls and instruction delimiters render as inert escaped data.
155
+ - Each task holds at most 32 probes, 128 operations/observations and a 1 MiB state envelope. Move a continuing investigation to a new task when full. Packet `--budget` / SDK `budget` ranges from 256 to 1,000,000 **heuristic units**; default 1,500. One unit is four serialized UTF-8 bytes: `estimatedTokens` (the compatibility field name) is `ceil(max(bytes.json, bytes.toon)/4)`. Thus both complete rendered packets, including newline and every accounting field, are bounded by `4 * budget` bytes. This is neither a tokenizer measurement nor a guaranteed upper bound on model tokens. No tokenizer or model encoding is used. `receipt.budgetUnit` names these heuristic units. The SDK fitter retains whole rows in order, skipping oversized rows and considering later rows. It refuses an infeasible mandatory receipt or exhausted fitting work with an actionable typed error.
156
+
157
+ Boundary declarations are authorization by the operator, not network discovery or a monitoring schedule. Historical observations never assert current health. The tool does not retain raw bodies, excerpts, cookies or credential values, and does not load credential files.
158
+
159
+ ## Without git
160
+
161
+ All probe, send, contract, compare, diff, missing and SDK operations work in an ordinary non-git directory. The fixtures and packed consumers fence ancestor discovery and exercise host commands without a git executable. Injected clients support read/compare/difference operations on other backends. Callers injecting remote clients must set `backend: 'remote'` explicitly. The current SDK's `commitItemMutations` requires a filesystem `pmRoot`; remote writes and sends refuse before effects until [pm-cli#1399](https://github.com/unbraind/pm-cli/issues/1399) supplies a backend-owned conditional writer. No remote mutation conformance is claimed.
162
+
163
+ ## Evidence and development
164
+
165
+ See [measured ten-request investigation](docs/real-data.md) and [architecture](ARCHITECTURE.md). The historical packet measured 817 bytes/4 heuristic units versus 25,847 body-only heuristic units for 103,388 captured raw body bytes; these are not model-token counts or an end-to-end cost comparison. Exact renderer bytes were not retained for that historical run, and the new receipt changes packet sizes. The run recorded ten observations, 90 header redactions, ten HTTP calls, 65,151 ms including SDK setup/recording. No credentials were sent, and the temporary tracker was deleted.
166
+
167
+ ```sh
168
+ npm run release:check
169
+ bun run release:check
170
+ npm run test:revert
171
+ npm run test:real-data # explicit public read-only requests, at most 20
172
+ ```
173
+
174
+ Release checks enforce 100% statements/branches/functions/lines across every authored source and tooling module, documented declarations, ESLint, zero duplication, production audit, an allowlisted package, generated pm-changelog output, publication attestation and packed consumers. Historical function proofs use the source checkout's Git history. Revert tests remove individual safety protections only in disposable copies and require behavioral failures, then rerun restored passing behavior. Tests use real SDK temp trackers and real node:http/HTTPS servers.
175
+
176
+ ## Exit codes
177
+
178
+ | Code | Meaning |
179
+ |---:|---|
180
+ | 0 | Command completed, including historical comparison violations or an uncertain recorded result; inspect structured verdicts/receipts |
181
+ | 2 | Invalid declaration, boundary/private destination refusal, absent credential, unsupported capability or safe SDK failure; read the remedy |
182
+ | 3 | Revision conflict; read current context and re-plan/recover |
183
+ | 130 | Caller cancellation; no partial observation admitted |
184
+
185
+ GitHub issue sync regenerates through `changelog:automation`, which runs the
186
+ same full generator that `changelog:check` verifies. This caller script keeps
187
+ the reusable workflow from injecting a different pending-release policy.
@@ -0,0 +1,116 @@
1
+ import { register } from './src/commands.ts';
2
+ /** Declare an immutable task-bound request. */
3
+ export declare const addProbe: (item: string, name: string, input: import("./src/types.ts").ProbeInput, options: import("./src/types.ts").Options) => Promise<{
4
+ probe: import("./src/types.ts").Probe;
5
+ revision: number;
6
+ }>;
7
+ /** Record a separate reviewed mutation capability. */
8
+ export declare const reviewProbe: (item: string, name: string, reason: string, options: import("./src/types.ts").Options) => Promise<{
9
+ probe: import("./src/types.ts").Probe;
10
+ revision: number;
11
+ }>;
12
+ /** Read complete request declarations. */
13
+ export declare const listProbes: (item: string, options: import("./src/types.ts").Options) => Promise<{
14
+ revision: number;
15
+ probes: import("./src/types.ts").Probe[];
16
+ receipt: {
17
+ complete: boolean;
18
+ omitted: number;
19
+ };
20
+ }>;
21
+ /** Preview without resolving credentials or writing. */
22
+ export declare const preview: (item: string, name: string, options: import("./src/types.ts").Options) => Promise<{
23
+ operation: string | undefined;
24
+ willSend: boolean;
25
+ revision: number;
26
+ method: string;
27
+ url: string;
28
+ headers: Record<string, string>;
29
+ body: string | undefined;
30
+ boundary: import("./src/types.ts").Boundary;
31
+ maxBytes: number;
32
+ timeoutMs: number;
33
+ credentials: string;
34
+ }>;
35
+ /** Execute one explicit journaled send; stable operation identities recover without duplicate effects. */
36
+ export declare const send: (item: string, name: string, options: import("./src/types.ts").Options) => Promise<{
37
+ observation: import("./src/types.ts").Observation;
38
+ operation: string;
39
+ }>;
40
+ /** Set an explicit bounded response expectation. */
41
+ export declare const setContract: (item: string, name: string, input: {
42
+ statuses: number[];
43
+ headers?: string[];
44
+ shape?: unknown;
45
+ maxLatencyMs?: number;
46
+ }, options: import("./src/types.ts").Options) => Promise<{
47
+ contract: import("./src/types.ts").Contract;
48
+ revision: number;
49
+ }>;
50
+ /** Read secret-free historical observations in process. */
51
+ export declare const observations: (item: string, options: import("./src/types.ts").Options) => Promise<{
52
+ revision: number;
53
+ observations: import("./src/types.ts").Observation[];
54
+ historical: boolean;
55
+ receipt: {
56
+ complete: boolean;
57
+ omitted: number;
58
+ };
59
+ }>;
60
+ /** Compare stored observations to current explicit contracts. */
61
+ export declare const compare: (item: string, options: import("./src/types.ts").Options & {
62
+ probe?: string;
63
+ }) => Promise<{
64
+ revision: number;
65
+ historical: boolean;
66
+ comparisons: import("./src/types.ts").Verdict[];
67
+ receipt: {
68
+ complete: boolean;
69
+ omitted: number;
70
+ };
71
+ }>;
72
+ /** Produce historical differences under a self-inclusive heuristic-unit budget with exact JSON/TOON UTF-8 byte costs. */
73
+ export declare const differencePacket: (item: string, options: import("./src/types.ts").Options & {
74
+ budget?: number;
75
+ }) => Promise<import("@unbrained/pm-cli").FittedOutputEnvelope<{
76
+ task: string;
77
+ revision: number;
78
+ historical: boolean;
79
+ rows: readonly unknown[];
80
+ estimatedTokens: number;
81
+ bytes: {
82
+ json: number;
83
+ toon: number;
84
+ };
85
+ receipt: {
86
+ sourceComplete: boolean;
87
+ omitted: number;
88
+ returned: number;
89
+ restore: string;
90
+ missing: string;
91
+ estimator: string;
92
+ budgetUnit: string;
93
+ };
94
+ }>>;
95
+ /** Enumerate exact outstanding evidence requests. */
96
+ export declare const missingEvidence: (item: string, options: import("./src/types.ts").Options) => Promise<{
97
+ revision: number;
98
+ missing: import("./src/types.ts").Missing[];
99
+ receipt: {
100
+ complete: boolean;
101
+ omitted: number;
102
+ };
103
+ }>;
104
+ /** Typed refusals with safe diagnostics and remedies. */
105
+ export { HttpError } from './src/core.ts';
106
+ /** Documented integration and durable record contracts. */
107
+ export type { Options, ProbeInput, Probe, Observation, Contract, Shape, State, Plan, Missing, Verdict, Step, Boundary, Review, CaptureReceipt } from './src/types.ts';
108
+ /** Native host integration; no request runs on activation. */
109
+ declare const _default: {
110
+ name: string;
111
+ version: string;
112
+ description: string;
113
+ activate: typeof register;
114
+ };
115
+ export default _default;
116
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAI7C,+CAA+C;AAC/C,eAAO,MAAM,QAAQ;;;EAAwB,CAAC;AAC9C,sDAAsD;AACtD,eAAO,MAAM,WAAW;;;EAA2B,CAAC;AACpD,0CAA0C;AAC1C,eAAO,MAAM,UAAU;;;;;;;EAA0B,CAAC;AAClD,wDAAwD;AACxD,eAAO,MAAM,OAAO;;;;;;;;;;;;EAAuB,CAAC;AAC5C,0GAA0G;AAC1G,eAAO,MAAM,IAAI;;;EAAoB,CAAC;AACtC,oDAAoD;AACpD,eAAO,MAAM,WAAW;;;;;;;;EAA2B,CAAC;AACpD,2DAA2D;AAC3D,eAAO,MAAM,YAAY;;;;;;;;EAA+B,CAAC;AACzD,iEAAiE;AACjE,eAAO,MAAM,OAAO;;;;;;;;;;EAA0B,CAAC;AAC/C,yHAAyH;AACzH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;GAAmC,CAAC;AACjE,qDAAqD;AACrD,eAAO,MAAM,eAAe;;;;;;;EAAkC,CAAC;AAC/D,yDAAyD;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,2DAA2D;AAC3D,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACtK,8DAA8D"}
package/dist/index.js ADDED
@@ -0,0 +1,30 @@
1
+ import { defineExtension } from '@unbrained/pm-cli/sdk/authoring';
2
+ import { register } from './src/commands.js';
3
+ import { guarded } from './src/core.js';
4
+ import * as api from './src/api.js';
5
+ import * as derive from './src/derive.js';
6
+ /** Declare an immutable task-bound request. */
7
+ export const addProbe = guarded(api.addProbe);
8
+ /** Record a separate reviewed mutation capability. */
9
+ export const reviewProbe = guarded(api.reviewProbe);
10
+ /** Read complete request declarations. */
11
+ export const listProbes = guarded(api.listProbes);
12
+ /** Preview without resolving credentials or writing. */
13
+ export const preview = guarded(api.preview);
14
+ /** Execute one explicit journaled send; stable operation identities recover without duplicate effects. */
15
+ export const send = guarded(api.send);
16
+ /** Set an explicit bounded response expectation. */
17
+ export const setContract = guarded(api.setContract);
18
+ /** Read secret-free historical observations in process. */
19
+ export const observations = guarded(derive.observations);
20
+ /** Compare stored observations to current explicit contracts. */
21
+ export const compare = guarded(derive.compare);
22
+ /** Produce historical differences under a self-inclusive heuristic-unit budget with exact JSON/TOON UTF-8 byte costs. */
23
+ export const differencePacket = guarded(derive.differencePacket);
24
+ /** Enumerate exact outstanding evidence requests. */
25
+ export const missingEvidence = guarded(derive.missingEvidence);
26
+ /** Typed refusals with safe diagnostics and remedies. */
27
+ export { HttpError } from './src/core.js';
28
+ /** Native host integration; no request runs on activation. */
29
+ export default defineExtension({ name: 'pm-http', version: "2026.11.19", description: 'Task-scoped explicit HTTP investigation context', activate: register });
30
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AACpC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAC1C,+CAA+C;AAC/C,MAAM,CAAC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC9C,sDAAsD;AACtD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;AACpD,0CAA0C;AAC1C,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AAClD,wDAAwD;AACxD,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAC5C,0GAA0G;AAC1G,MAAM,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACtC,oDAAoD;AACpD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;AACpD,2DAA2D;AAC3D,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;AACzD,iEAAiE;AACjE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC/C,yHAAyH;AACzH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;AACjE,qDAAqD;AACrD,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;AAC/D,yDAAyD;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG1C,8DAA8D;AAC9D,eAAe,eAAe,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,iDAAiD,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC"}
@@ -0,0 +1,56 @@
1
+ import type { Contract, Observation, Options, Plan, Probe, ProbeInput, State } from './types.ts';
2
+ /** Locate a canonical probe with prototype-safe lookup. */
3
+ export declare function probeFrom(value: State, name: string): Probe;
4
+ /** Bind effect admission to the original caller policy, identity and lifecycle, never mutable guard selectors. */
5
+ export declare function assertPlanGuard(value: State, entry: Plan | undefined, original: Plan, callerRevision: number | undefined, phase: 1 | 2, sourceDigest: string | undefined): asserts entry is Plan;
6
+ /** Share operation identity, guard and recording-capacity admission between preview and apply. */
7
+ export declare function admitPlan(value: State, probe: Probe, id: string, expectedRevision: number | undefined, sourceDigest: string): boolean;
8
+ /** Declare an immutable request bound to an existing native task. */
9
+ export declare function addProbe(item: string, name: string, input: ProbeInput, options: Options): Promise<{
10
+ probe: Probe;
11
+ revision: number;
12
+ }>;
13
+ /** Record separate mutation review with attributed author and an explicit reason. */
14
+ export declare function reviewProbe(item: string, name: string, reason: string, options: Options): Promise<{
15
+ probe: Probe;
16
+ revision: number;
17
+ }>;
18
+ /** List complete declarations with a source-completeness receipt. */
19
+ export declare function listProbes(item: string, options: Options): Promise<{
20
+ revision: number;
21
+ probes: Probe[];
22
+ receipt: {
23
+ complete: boolean;
24
+ omitted: number;
25
+ };
26
+ }>;
27
+ /** Preview the same request planner used by send, without resolving credentials or writing. */
28
+ export declare function preview(item: string, name: string, options: Options): Promise<{
29
+ operation: string | undefined;
30
+ willSend: boolean;
31
+ revision: number;
32
+ method: string;
33
+ url: string;
34
+ headers: Record<string, string>;
35
+ body: string | undefined;
36
+ boundary: import("./types.ts").Boundary;
37
+ maxBytes: number;
38
+ timeoutMs: number;
39
+ credentials: string;
40
+ }>;
41
+ /** Send using a durable intent; uncertain interrupted sends converge without replaying the request. */
42
+ export declare function send(item: string, name: string, options: Options): Promise<{
43
+ observation: Observation;
44
+ operation: string;
45
+ }>;
46
+ /** Store one normalized contract, replacing the prior expectation under current revision. */
47
+ export declare function setContract(item: string, name: string, input: {
48
+ statuses: number[];
49
+ headers?: string[];
50
+ shape?: unknown;
51
+ maxLatencyMs?: number;
52
+ }, options: Options): Promise<{
53
+ contract: Contract;
54
+ revision: number;
55
+ }>;
56
+ //# sourceMappingURL=api.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAQ,MAAM,YAAY,CAAC;AAEvG,2DAA2D;AAC3D,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,SAAgO;AACpR,kHAAkH;AAClH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,GAAG,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAMhM;AACD,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAarI;AACD,qEAAqE;AACrE,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO;;;GAI7F;AACD,qFAAqF;AACrF,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;;;GAK7F;AACD,qEAAqE;AACrE,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;;;;QAA+H,QAAQ;QAAQ,OAAO;;GAAU;AAC/N,+FAA+F;AAC/F,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;;;;;;;;;;;;GAMzE;AACD,uGAAuG;AACvG,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAyEjI;AACD,6FAA6F;AAC7F,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,OAAO;;;GAOxK"}