Skip to content

Adds executeTagged to the tagged subpath - #162

Merged
johnnyt merged 2 commits into
mainfrom
pts-mmls-execute-tagged
Oct 1, 2026
Merged

johnnyt merged 2 commits into
mainfrom
pts-mmls-execute-tagged

Conversation

@johnnyt

@johnnyt johnnyt commented Oct 1, 2026 •

Copy link
Copy Markdown
Member

What

executeTagged on the ./tagged subpath: the statement run beside evaluateTagged. execute and executeValue hand a program's halt context back under the plain projection, so a program that stores the float two reads back the integer two. executeTagged runs the same statement program and answers the halt context as the tagged encoding's text on both arms, so decodeTagged reads every value back as the one the program bound - an integral float stays a float, and a date, a datetime, a duration and an absence come back as themselves.

Adding this name to this release was ruled by the operator, 2026-10-01.

  • src/tagged.ts: executeTagged(program: Program | string, context?, options?: EvaluateOptions). A list runs as given; a string is compiled with compileProgram, and a refusal is that ParseError on the failing arm with no context. The run is executeToContext, the function execute runs, so the options, budgets and refusals are execute's and the caller's context is never written into. The failing arm carries the partial context in the same encoding, and none when the value boundary refused the context.

  • test/export-surface.json: executeTagged added to the ./tagged list.

  • README.md: documented beside evaluateTagged in "The tagged subpath", with an executed example; the entry-points import line and the subpath bullet name it.

  • changelog.d/pts-mmls.md: an Added fragment naming it.

  • src/index.ts: execute's doc comment points a host that needs the brand at executeTagged. No code change there.

  • docs/adr/0002-the-value-domain-and-the-host-boundary.md: a dated foot Note, below.

No change under src/evaluator.ts; executeToContext was already exported from that module.

Record

One ## Note at the foot of ADR-0002, add-only (git diff origin/main...HEAD -- docs/adr/ shows no removed line) and with no Status line. It names executeTagged as a fifth function in the note "the projection is an export and is not an entry point for host input", whose sentence opening "Those are evaluate, execute and executeValue" listed four. It says tagged is still accepted by evaluateTagged alone, since executeTagged takes EvaluateOptions and always answers the encoding, which keeps the Decision's "accepted by the entry point that subpath exports and by no other" and the options note's "the subpath's entry point, evaluateTagged" true of the option. It also says this change discharges the sentence in the amendment on the three questions the statement-mode note holds: "a change that gives it one owes the encoding across the returned context".

Why a Note and not an Amendment: docs/adr/README.md says an amendment changes what the record decides and a note does not. The listing sentence is itself inside a note, which decides nothing. The statement-mode amendment already anticipated a statement run on the subpath and stated what it owes. Adding this function was ruled by the operator, 2026-10-01. So this text records which accepted sentences a new function falls under and how each still reads, and decides nothing.

Direction check, done in-turn: each quoted sentence was matched against the record's text at 929bcb7. The claim that encodeTagged refuses a cyclic value, one past the depth limit and one past the place budget rather than raising was checked against its doc comment and code in src/tagged.ts. The main-entry claim was checked against execute and executeValue in src/index.ts, which still answer the plain projection.

Provenance

Engineering choices this PR makes, each reversible before the release prep:

  • The encoding is the only form it answers in, and it takes the main entry point's options. There is no tagged request: a plain default would answer exactly what execute answers, and keeping the tagged option on evaluateTagged alone leaves docs/adr/0002-the-value-domain-and-the-host-boundary.md's statements about that option as they are. The result shape mirrors evaluateTagged's arms (ok, the answer, error), with the context in place of the value, as execute's does.
  • A source string compiles as a statement program through compileProgram, independent of whether execute's own source form has switched to program mode; nothing here depends on that change.
  • A context the encoding cannot carry. On the successful arm it is a failure carrying the encoder's reason as an EvaluationError, with no context. On the failing arm the run's own error stays the answer and the context it cannot write is left off.
  • No new exported type. The result type is declared in the module and not exported; the only new public name is executeTagged, which test/export-surface.json pins.
  • Fixtures and the README example use the library loan. The repository's CLAUDE.md names the card-processing and signup-wizard domains for examples; this campaign's consent asks for the canonical example domains, so the new tests and example use the library world. Flagged for the conductor rather than settled here.

Rebased onto 929bcb7, which exported DecompileResult and added its name to test/export-surface.json's . list. This change adds to the ./tagged list, so the rebase applied with no conflict and both names are kept. The open change that switches execute's source form to program mode also edits README.md and execute's doc comment in src/index.ts. A rebase over it is additive.

Tests

New executeTagged tests in test/tagged.test.ts pin: the float two on the success arm from source text; the compiled-list form; the partial context on the failure arm (a protected-root refusal) with the float intact; a date, a duration and an absence; the loop budget's refusal with the context it reached; a source the program compiler refuses and a context the value boundary refuses, both with no context; a halt context the encoding cannot carry; the run's own refusal kept when its partial context cannot be encoded; and that the caller's context is not written into.

Sabotage, each run against test/tagged.test.ts with the file restored byte-equal before the next; every failure was an assertion failure:

Mutation in src/tagged.ts Tests that went red (in the executeTagged describe block)
project the context (both arms) before encoding keeps an integral float a float on the success arm, from source text; runs a compiled program the same way it runs its source; answers the partial context the same way on the failure arm; carries the dates, durations and absences a plain projection loses
project only the failing arm's partial context before encoding answers the partial context the same way on the failure arm
compile a source string as an expression instead of a statement program keeps an integral float a float on the success arm, from source text; answers the partial context the same way on the failure arm; carries the dates, durations and absences a plain projection loses; answers the loop budget's refusal with the context the run reached; answers a context the value boundary refuses with no context; answers a halt context the encoding cannot carry as a failure; keeps the run's own refusal when its partial context cannot be encoded
let the encoder's refusal through as a success answers a halt context the encoding cannot carry as a failure
hand back an empty text for an unencodable partial context keeps the run's own refusal when its partial context cannot be encoded

Gate

mise exec -- pnpm run gate green on the rebased head: typecheck, lint, neutrality, the suite with coverage (35 files, 2833 tests passed), corpus:check at v9.4.2, build, identity and resolution all passed. CI runs the same gate.

execute and executeValue hand a statement program's halt context back
under the plain projection, so a program that stores the float two
reads back the integer two. executeTagged, on the tagged subpath beside
evaluateTagged, runs the same statement program - a compiled list, or
source text compiled as compileProgram compiles it - and answers the
halt context as the tagged encoding's text on both arms, so
decodeTagged reads every value back as the one the program bound.

The run is execute's: the main entry point's options, the same budgets
and refusals, and the caller's context never written into. A source
the program compiler refuses is its ParseError with no context; a
context the value boundary refuses carries none either. A halt context
the encoding cannot carry is the encoder's reason as an
EvaluationError; on the failing arm the run's own error stays the
answer and the context it cannot write is left off.

It takes no tagged request: the encoding is the only form it answers
in, and the tagged option stays evaluateTagged's alone.

Tests pin the float on both arms, the compiled-list form, dates,
durations and absences, the loop budget, both no-context refusals and
both encoding refusals; each new sabotage was run and reverted. The
README documents it beside evaluateTagged, and an Added fragment
names it.

Refs: pts-mmls
Adds a dated foot Note to ADR-0002, add-only, that decides nothing. The
note defining an entry point as a function that runs a program and
answers its result listed four such functions; executeTagged is a
fifth and the tagged subpath's second. The Note says the tagged option
is still accepted by evaluateTagged alone, since executeTagged takes
EvaluateOptions and always answers the encoding, and that this change
discharges the statement-mode amendment's sentence that a change giving
the subpath a statement mode owes the encoding across the returned
context.

Also states in the README that on the failing arm the run's own error
stays and an unencodable partial context is left off, and points
execute's doc comment at executeTagged for a host that needs the brand.

Refs: pts-mmls
@johnnyt
johnnyt force-pushed the pts-mmls-execute-tagged branch from 2997bd3 to a7c0975 Compare October 1, 2026 12:58
@johnnyt
johnnyt merged commit 5afceb8 into main Oct 1, 2026
1 check passed
@johnnyt
johnnyt deleted the pts-mmls-execute-tagged branch October 1, 2026 13:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant