deepclause-sdk 0.1.1 → 0.1.3

package/dist/system/assets/docs/DML_AUTHORING.md

@@ -41,6 +41,63 @@ plausibly reuse the predicate with different arguments; if only this request
 would, do not add it. A harness of many task-shaped helpers is as bad as one
 hard-coded script.
 
+**Declare the shape of structured model output.** `list(object(B))` does not say
+what is in the dicts, so every consumer re-derives defaults and tolerates missing
+fields by hand. `schema(Name, [field(Field, Type, Option)])` is checked when the
+result binds: defaults filled, a missing `required` field or a wrong type reported
+against the field name, an undeclared field kept so a mistake stays visible. Name it
+in the output — `task(…, list(schema(author, Authors)))` — or apply it by hand with
+`schema_fill(author, Raw, Author)`.
+
+**Know which conversation the model sees.** `task/N` is sent the memory built so
+far and writes its reply back, so consecutive `task/N` calls accumulate history —
+pass values as explicit arguments instead of relying on the model to remember them.
+`prompt/N` is fresh (no memory, no tools) and is the right choice for a classifier,
+extractor, or transformation that must not be swayed by the conversation;
+`with_fresh_memory(Goal)` does the same for a group of steps, and restores the
+caller's memory on exit. A `task/N` inside a `tool/2` body starts empty: give it the
+context as an argument.
+
+**Start small, then improve.** Write the smallest harness that answers the actual
+request end to end — often a single predicate — run it on a real input, and show
+the user the result *before* extending it. Say what it does, what it does not do
+yet, and what you would add next, then let the next request decide. A harness grows
+in the direction the user actually takes it.
+
+Adding capability speculatively is the expensive mistake, and it costs more here
+than in a normal codebase: every predicate is part of the harness the next turn has
+to reason about, and every helper is one more thing the model can be offered as a
+tool. Do not write an error taxonomy before an error has occurred, retry and
+fallback policies before something has failed, caching or configuration layers
+before there is a reason, or a predicate per case for cases you have not seen.
+Prefer the smallest change that makes the failing input work.
+
+Signs you are overengineering:
+
+- a predicate with one caller whose arguments are all literals from the request;
+- an abstraction (a schema, an options list, a dispatch table) built for a single
+  shape or a single value;
+- a helper "framework" written before the first end-to-end run;
+- generalizing across cases that no one has asked for yet;
+- a harness that does not run yet, because the parts are still being made tidy.
+
+A small change is also easier to trust: each commit is one reviewable unit, the
+`end_turn` probes report on a small surface, and `rollback` stays cheap. A harness
+that is incomplete but working is a better answer than one that is complete and
+unverified.
+
+**Do not parse in DML — shell out or ask the model.** Prolog string handling is
+the fiddliest thing here, and a hand-rolled parser (`sub_string/5`,
+`split_string/4`, `atom_concat/3`, `format/2`, an accumulator) is the easiest way
+to write DML that looks right and is quietly wrong. Split the work by what it is.
+Mechanical work — pull a field, change a format, count, filter — belongs in a
+**helper script** (`script_file/2` + `exec(bash(argv: [...]))`), which is testable
+outside DML and written in a language made for text; have it emit **JSON** and read
+it with `json_get/3`/`json_gets/3`/`json_text/2` instead of splitting stdout.
+Work that needs *understanding* — find the field named X, classify, summarise —
+belongs in a **model call** with a typed output (`task("…", list(string(Items)))`,
+`schema/2`, `choose`/`rate`/`verify`). DML sequences and checks; it does not parse.
+
 **Prefer orchestration over algorithms.** A skill should read as a short
 sequence of steps. Describe each step with `task/N` (which sees the conversation
 memory) or `prompt/N` (fresh context) and let the model extract, classify,
@@ -131,6 +188,12 @@ doc(tally/2, "Count occurrences of each item. tally(+List, -Counts) yields Key-N
   same predicate is callable from `execute` / `/goal` **and** from `task/N`. Logic
   placed only inside `tool/2` is unreachable from `execute` (the loader asserts
   `tool(Head)`, never `Head`).
+  - Annotate **capabilities** (file I/O, search, a script) that a nested agent
+    should use — not the LLM steps themselves. A `tool/2` whose implementation
+    calls `task/N` and advertises the same job is offered to the agent inside that
+    `task/N`, which then calls it. Absent the tool call stack, wrapper predicates
+    are the same job twice; keep the step a skill, or scope the task with
+    `without_tools([Head], task(…))`.
 - `doc(Name/Arity, Text)` — one fact per skill, helper, or tool; terse, with
   arguments (`+in` / `-out`) and an example goal.
 
@@ -159,24 +222,33 @@ text-only — never attach media to them.
 ## 6. Guard rails
 
 - Read first: call `listing`.
-- **Paths are workspace-relative and workspace-confined.** Never write
-  `/workspace/...` or any absolute path in DML — they are rejected. `size_file/2`,
-  `time_file/2`, `read_file/2`, `open/3`, `directory_files/2`, and `read_media/2`
-  all take a relative path, and `directory_files/2` returns **bare names**, so
-  build one (`atom_concat('images/', Name, Path)`). `bash` sees more of the
-  sandbox than DML can — keep that in `bash` and hand DML only relative paths.
-  Prefer `bash`/host file tools for file operations; use the DML file predicates
-  only for content you must reason over in Prolog.
+- **Paths: use `/workspace/...`.** The workspace is the working directory, so
+  `out/report.txt` and `/workspace/out/report.txt` are the same file — but write
+  the `/workspace` form, because it means the same thing from DML, from
+  `exec(bash(...))`, and from the shell tool on every backend. Everything outside
+  `/workspace` is the session's ephemeral VM filesystem: fine for scratch, never
+  for a result, because **only files under `/workspace` reach the host**. Scratch
+  goes in `$TMPDIR` (per-session in every backend), not a bare `/tmp`.
+  `directory_files/2` returns **bare names**, so build one
+  (`atom_concat('images/', Name, Path)`). Prefer `bash`/host file tools for file
+  operations; use the DML file predicates only for content you must reason over
+  in Prolog.
 - **Side-effecting skills must be deterministic.** Any skill that calls
   `task/N`, `prompt/N`, `exec/2`, `read_media/2`, `attach_media/1`, or writes a
   file must yield exactly one solution with no choicepoint left across the side
   effect (`once/1`, `->`, or a cut). Otherwise backtracking re-runs the model
   call: slow, costly, and a different answer each time.
-- Replace a predicate with `define(head, clauses)` (or `retract` then
-  `assert_many`). `assert` appends, so asserting a clause twice duplicates the
-  predicate; never patch it clause by clause.
-- Clause order matters: base case before a recursive rule; define a whole
-  predicate with `assert_many` (clauses in the order written).
+- Replace a predicate with `define(head, clauses)`, where the head names the
+  predicate being replaced and must be one of the predicates the block defines.
+  Never patch it clause by clause.
+- `assert`/`assert_many` are for a **new** predicate: they append, so against an
+  existing one both versions would stay live with their clauses interleaved, and
+  the runtime refuses the call rather than let that happen.
+- `retract` removes the clauses matching its pattern and says how many; `delete`
+  removes a whole predicate. `retract` fails when nothing matched — check that
+  the pattern is the one you meant.
+- Clause order matters: base case before a recursive rule; give a whole predicate
+  to `define`/`assert_many` at once (clauses in the order written).
 - Verify after changing a predicate: `listing(Name/Arity)`.
 - Bounded iteration only: finite recursion or an explicit bound. `execute` is
   gas-limited and the turn has a model-call budget, but a single builtin call
@@ -185,10 +257,17 @@ text-only — never attach media to them.
   domain (`X ins 0..N`) before `label/1`, prefer `once/1`, and keep the model
   small: an under-specified or unsatisfiable model searches forever, and there
   is no per-goal timeout. Never reach for CLP as a shortcut for arithmetic.
-- `bash` runs in a sandbox. Explore it (`python3 --version`, `pip list`,
-  `which jq`) and install a dependency when a skill genuinely needs one;
-  installs are sandbox/session-local and do not travel with an exported harness,
-  so prefer the standard library.
+- **Know whether you are sandboxed.** The session's environment block says which
+  backend is in effect. With a sandbox (`bwrap`, AgentVM, `sandbox-exec`),
+  `bash` is isolated and writes outside the workspace are confined. With
+  `clean-room` there is **no** sandbox: commands run as the user, writes outside
+  the workspace are real files that persist, and a `rm` is a real `rm`. Explore
+  what is available (`python3 --version`, `pip list`, `which jq`) and install a
+  dependency when a skill genuinely needs one; installs are sandbox/session-local
+  and do not travel with an exported harness, so prefer the standard library.
+- If a harness genuinely requires isolation, the **user** can add
+  `:- require_sandbox.` (through `/set-require-sandbox`). It makes the load fail
+  rather than run unsandboxed. Do not add it yourself.
 - Do **not** use `agent_main` unless the user asks for a `deepclause run` /
   `/dc-run` skill.
 - Media: reference images with `media(Path, Mime)` (`read_media/2` +