# Semantic operations > Every external effect in a document is a named semantic operation, with explicit parameters and an explicit binding for its result; invocation parts] names… Page: PAG · Guide Canonical: https://banes-lab.com/pag/guide#tool-invocation This section is stop 17 of 102 in the learning route. Previous: [02 - Document structure](https://banes-lab.com/pag/guide/document-structure.md). Next: [04 - Node design](https://banes-lab.com/pag/guide/node-design.md). It builds on [01 - Writing a first document](https://banes-lab.com/pag/guide/getting-started.md). Every external effect in a document is a named semantic operation, with explicit parameters and an explicit binding for its result; [C1·e invocation parts](https://banes-lab.com/pag/guide#tool-invocation-panel-e) names those parts, and [C1·c invocation forms](https://banes-lab.com/pag/guide#tool-invocation-panel-c) writes them four ways. The operation says what happens, and [C1·a the operations](https://banes-lab.com/pag/guide#tool-invocation-panel-a) groups the operations by the kind of effect. An adapter outside the document, one per harness, decides how the effect is carried out, which is the split shown in [C1·b document and adapter](https://banes-lab.com/pag/guide#tool-invocation-panel-b) and [C1·d one adapter per harness](https://banes-lab.com/pag/guide#tool-invocation-panel-d). An invocation is the act stage of [the loop](https://banes-lab.com/disciplined-methodology/start/the-loop.md), and it yields a procedure. ### Operations, not tools An effect described in prose is not addressable by any adapter, and an effect named by one harness's tool is [hardcoded configuration](https://banes-lab.com/records/arch/hardcoded-configuration.md) that only that harness can address. A library of documents names one harness's tools throughout, the harness changes its tool set, and every document breaks at once, which is [vendor lock-in leakage](https://banes-lab.com/records/arch/vendor-lock-in-leakage.md) with nothing in any document to explain it. A tool name is a fact about one harness, and a document that carries it is bound to that harness by the first line that does. For this reason a document names semantic operations, and one adapter resolves them to tools by [late binding](https://banes-lab.com/records/arch/late-binding.md). The document is separated from the harness at the operation, with one adapter per harness, rather than one document being written per harness. In practice, every effect is named with a semantic operation and given a target, its parameters are passed through a named clause, and its result is bound to a name the next line can read. A location or a command is referred to through a slot the adapter resolves, never through a literal path, and the harness's own tool names, configuration files and features stay out of the document. To check this, rename the harness under the document and hand it to a different model. Where a line fails, it carried a tool name or a path where an operation or a slot belonged, and the fix belongs in the adapter. A document written for exactly one throwaway session may name whatever it likes, because nothing will port it. The discipline is for a document that will be walked again, by another party, or under another harness. The operations fall into three groups by the kind of effect: those that act on a tree and produce values, those that leave an artifact in it, and those that reach outside it or address another party. Each operation carries a [semantic contract](https://banes-lab.com/records/arch/semantic-contracts.md), so a document relies on the contract rather than on what a particular tool happens to do. [Portability](https://banes-lab.com/records/arch/portability.md) follows from this boundary. Operations and slots in the document are [configuration externalization](https://banes-lab.com/records/arch/configuration-externalization.md) applied to an instruction, and one adapter per harness is the [adapter pattern](https://banes-lab.com/records/arch/adapter-pattern.md). A slot with no counterpart in a harness resolves as absent, as described under [limits](https://banes-lab.com/pag/validation/limitations.md). A decision request is the clearest case: a participant has a question surface and a bounded reader does not, so the same operation resolves for one and is absent for the other, while the document stays unchanged. The model a document runs under is always a slot, because choosing the model belongs to the harness. C1·a the operations ```pag # SEMANTIC OPERATION BOUNDARY · a node states WHAT as an operation; an adapter decides HOW # discover, read, search, analyze · operations against a tree that produce values DISCOVER_RESOURCES "" INTO READ_RESOURCE INTO SEARCH_CONTENT FOR INTO ANALYZE_CONTENT AGAINST INTO EXTRACT_FACTS FROM INTO CALCULATE_METRIC FROM INTO # compose, validate, persist · operations that leave an artifact COMPOSE_ARTIFACT FROM USING VALIDATE_ARTIFACT AGAINST PERSIST_ARTIFACT TO # execute, decide, report · effects outside the tree and on other parties EXECUTE_TOOL WITH timeout: INTO REQUEST_DECISION WITH options: [, ] INTO REPORT_RESULT TO ``` C1·b document and adapter ```pag # the document names an operation and a slot · one adapter per harness resolves both, outside the document READ_RESOURCE {project.governance_policy} INTO EXECUTE_TOOL {toolchain.verify_command} INTO adapter: DISCOVER_RESOURCES → READ_RESOURCE → SEARCH_CONTENT → EXECUTE_TOOL → PERSIST_ARTIFACT → REQUEST_DECISION → {project.governance_policy} → {toolchain.verify_command} → ``` C1·c invocation forms ```pag READ_RESOURCE # the operation and its target READ_RESOURCE INTO # bound to a name the next line reads SEARCH_CONTENT FOR WITH glob: "*.md" # named parameters EXECUTE_TOOL → # the arrow is the same binding ``` C1·d one adapter per harness ```mermaid flowchart TB doc["The document · semantic operations and {slots}"] adapter["One adapter per harness"] harnessA["Harness A · its read tool, its shell, its question surface"] harnessB["Harness B · different tools, same document"] absent["A slot with no analogue · declared ABSENT, the branch does not run"] doc --> adapter adapter --> harnessA adapter --> harnessB adapter -. no analogue .-> absent ``` C1·e invocation parts ```mermaid flowchart LR op["Operation · what happens"] target["Target · what it acts on"] params["WITH · named parameters"] result["INTO or arrow · where the result lands"] addressable["An effect the adapter can perform and the next line can read"] op --> target --> params --> result --> addressable ``` ## Links to - [The loop](https://banes-lab.com/disciplined-methodology/start/the-loop.md) - [Vendor Lock-In Leakage](https://banes-lab.com/records/arch/vendor-lock-in-leakage.md) - [Late Binding](https://banes-lab.com/records/arch/late-binding.md) - [Hardcoded Configuration](https://banes-lab.com/records/arch/hardcoded-configuration.md) - [Semantic Contracts](https://banes-lab.com/records/arch/semantic-contracts.md) - [Portability](https://banes-lab.com/records/arch/portability.md) - [Configuration Externalization](https://banes-lab.com/records/arch/configuration-externalization.md) - [Adapter Pattern](https://banes-lab.com/records/arch/adapter-pattern.md) - [Limits](https://banes-lab.com/pag/validation/limitations.md) ## Linked from - [What PAG is](https://banes-lab.com/pag/introduction/what-is-pag.md) - [Keywords](https://banes-lab.com/pag/keywords/keyword-ontology.md) - [BNF grammar](https://banes-lab.com/pag/grammar/bnf-grammar.md) - [Core templates](https://banes-lab.com/pag/templates/templates-core.md) - [The behaviour document](https://banes-lab.com/disciplined-methodology/start/the-behaviour-document.md) - [The drop-in](https://banes-lab.com/disciplined-methodology/start/onboarding.md) - [Tools live in the tree](https://banes-lab.com/disciplined-methodology/build/tools-live-in-the-tree.md)