Repository navigation
Planner: loops, rethrow-only handlers and passed-down values worded by their result; no application handle across a library call #4690
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -72,7 +72,9 @@ Inputs, outputs, side effects. Mandatory content for a component inside a proces | |||||
|
|
||||||
| **Library components** (a project other components consume as a package) carry, instead of the three bullets, one table per public workflow — never one table shared by several, which hides each workflow's types and directions: `Argument | Direction | Type | Description`. The Type is the one the rebuild gives the argument — a flag is a Boolean and a count a number, whatever text the source carried them in — and the description states the default and the value format (what a flag means, how a date is rendered, which side quotes a value), plus the conventions consumers rely on (naming, defaults, what a failed final check does). This table is the contract consumers are authored against before the library packs; every detail it omits becomes a question between two build groups. A workflow over the analyzer's argument cap (20) carries its optional switches and values in one options object — one In argument with its own table (`Field | Type | Default | Description`). | ||||||
|
|
||||||
| **State kept between calls.** A library workflow starts each call from its declared defaults, and a library project holds no global variables or constants, so state the source keeps from one call of its actions to the next — a value one action stores and another reads, an attached application or handle, its own instance of another component it calls — lives in the consumer and crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field does outlive a call, but as one value for every caller in the job and none inside an isolated invoke, and no Interface shows it, so it holds none of this state. An attached application crosses as the application handle the owning skill's public-workflow contract has workflows return and accept. The conventions name the holder and the work the source ran on its own — set-up before the first call, a close-down when the run ends, after a failure too — each a public workflow the holder calls at that point. The holder follows the source's instances, as the source guide's § Call Graph Rules state them: an instance per caller is held by each caller — a process in its entry workflow for its whole run, passed to the workflows that call the library, and a calling library in its own Interface, since it holds nothing either; one instance per run is held by the run's entry workflow and passed to every caller, calling libraries included. A stored value no action changes is no state: it is a fact or a Configuration Question (§ Configuration Questions). | ||||||
| **State kept between calls.** A library workflow starts each call from its declared defaults, and a library project holds no global variables or constants, so state the source keeps from one call of its actions to the next — a value one action stores and another reads, its own instance of another component it calls — lives in the consumer and crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field does outlive a call, but as one value for every caller in the job and none inside an isolated invoke, and no Interface shows it, so it holds none of this state. An attached application is no state that crosses a call: a library hands no application handle out for a caller to pass to another call, and each activity gets the application through its own Use Application/Browser card where it uses it. The conventions name the holder and the work the source ran on its own — set-up before the first call, a close-down when the run ends, after a failure too — each a public workflow the holder calls at that point. The holder follows the source's instances, as the source guide's § Call Graph Rules state them: an instance per caller is held by each caller — a process in its entry workflow for its whole run, passed to the workflows that call the library, and a calling library in its own Interface, since it holds nothing either; one instance per run is held by the run's entry workflow and passed to every caller, calling libraries included. A stored value no action changes is no state: it is a fact or a Configuration Question (§ Configuration Questions). | ||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🔸 Non-blocker · How a workflow gets its application is Fix: (the builder copy,
Suggested change
|
||||||
|
|
||||||
| **A value passed down only to reach its reader is the reader's own read.** A value that is the same wherever and whenever the run reads it — the machine name, the user name, the robot's name — and that the source reads once and passes through calls only to reach the step that uses it is read by that step, and is no argument of the workflows it passes through. A value the caller computes or changes, or one that must hold the value of one moment for the whole run (the run's start time), stays an argument. | ||||||
|
|
||||||
| **Test components** (a group of test cases over data rows in the single test project) list the row schema per test case: the fields that vary per scenario, separately from the constants in the project's configuration. Credentials appear as the name of a credential asset per row, never as values. Each case names its data set — a single row included — with its row count and where the source keeps it, since the rebuild keeps it there: a data set kept in a store is the case's data source, the project's test-data entity filtered on the data set's name; one shipped with the project is a variation file in the owning skill's format, named after the case, whose fields stay within the analyzer's argument cap (above). A case with no data set takes its values from configuration constants. | ||||||
|
|
||||||
|
|
@@ -122,6 +124,8 @@ Test: if a builder cannot rebuild the step from the text alone, add detail. Neve | |||||
|
|
||||||
| **A source's workaround for its own platform is not behaviour.** A clipboard copy between two ranges, a temporary file written beside the input, a rename around a path the source's script cannot open, a user setting switched to steer a file format: the step states the result the workaround produced, and the Source Map names the workaround — unless a later step reads what it leaves behind, which makes it data. | ||||||
|
|
||||||
| **A loop that only computes, selects or tests is its result.** A loop whose body only sets a field of each row, copies the rows a condition passes into another table, or sets a flag when a row passes is written as what it produces: "{field} of every row is …", "the rows of {table} where …", "whether {table} holds a row where …". The loop is a step of its own only when its body acts on an application, a file or a queue, or calls another step. | ||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🔸 Non-blocker · None of the three forms fits a loop that adds each row's amount to a total or counts rows, a common computing loop. Fix:
Suggested change
|
||||||
|
|
||||||
| ### Business Rules | ||||||
| Plain language, no code syntax, specific fields and thresholds kept. Group under `### Step N: {name}` headings for the step where the rule fires; a rule or handler several steps share goes once under a heading naming them (`### Steps 4, 10 and 15: …`); cross-step rules under `### General`. | ||||||
|
|
||||||
|
|
@@ -138,6 +142,8 @@ Plain language, no code syntax, specific fields and thresholds kept. Group under | |||||
| ### Error Handling | ||||||
| Same step-associated layout as Business Rules, plus `### Global`. Behavioural wording: "Retries 3× on timeout, then routes the item to the exception queue" — never "RetryScope with NumberOfRetries=3". An entry states the failure, the outcome and the level that handles it; a failure that every UI step shares ("expected element not found: screenshot, stop naming the step") is written once under `### Global`, not repeated per step, and a step entry exists only where that step's handling differs. A Workflow substep's "confirm …" is a post-condition of the action before it, not a separate check (execution builds it as that action's verification). | ||||||
|
|
||||||
| **A handler that only rethrows is no handling.** A catch whose only action is to raise the failure it caught again, unchanged, handles nothing: the failure goes on as if nothing had caught it, and no Error Handling entry describes the catch. A handler that logs, cleans up, retries, changes the failure or chooses between outcomes before it rethrows is an entry, stated by what it does. | ||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🔴 Blocker · A rethrow-only catch ahead of a broader catch is handling: it keeps that failure from the broader handler.
Fix:
Suggested change
|
||||||
|
|
||||||
| ### Transactional Shape | ||||||
| Whether the automation iterates over units of work — items that succeed, fail, are retried and are tracked independently of one another — and, when it does, per flow how the work is handled today and how it could be divided at build, asserting no split except one a `Decided:` line records: [transactional-shape-guide.md](transactional-shape-guide.md). A genome with no unit of work carries the stub line (§ Stub Lines). | ||||||
|
|
||||||
|
|
||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🔸 Non-blocker · Same change as the planner copy (
genome-format-guide.md:75): the two copies change together.Fix: