deepclause-sdk 0.1.1 → 0.1.3

package/dist/prolog-src/deepclause_mi.pl

@@ -61,6 +61,13 @@
     repl_edit_touched/2,
     repl_edit_touched_text/2,
     repl_edit_touched_clear/1,
+    repl_validate_tools/2,
+    repl_validate_docs/2,
+    schema_fill_fields/3,
+    schema_fields_of/3,
+    repl_unhandled_directives/2,
+    repl_inject_workspace_predicates/1,
+    workspace_predicate_name/1,
     repl_set_dml_reference/2,
     repl_set_authoring_examples/2,
     repl_manifest/2,
@@ -116,6 +123,7 @@
 :- dynamic session_repl_memory/2.   % session_repl_memory(SessionId, HarnessMemory) - object/entry memory
 :- dynamic session_meta_memory/2.   % session_meta_memory(SessionId, MetaMemory) - code-writing task memory
 :- dynamic session_repl_mode/2.     % session_repl_mode(SessionId, true/false) - gates format/writeln output shims
+:- dynamic session_unhandled_directive/2. % session_unhandled_directive(SessionId, Directive)
 :- dynamic session_frozen/2.        % session_frozen(SessionId, true/false) - read-only lock
 :- dynamic session_locked/2.        % session_locked(SessionId, true/false) - irreversibly frozen (--locked)
 :- dynamic session_directive/2.     % session_directive(SessionId, Directive) - recorded :- directives for export
@@ -153,7 +161,8 @@
 parse_dml(FilePath, SessionId, _MemoryId, Params, Error) :-
     catch(
         (
-            read_file_to_string(FilePath, Code, []),
+            % FilePath is an absolute host temp path, not workspace-relative.
+            system:read_file_to_string(FilePath, Code, []),
             assert_params(SessionId, Params),
             parse_dml_string(Code, SessionId),
             Error = none
@@ -310,6 +319,11 @@ extract_var_info(Bindings, Term, BareVar, Info) :-
         BareVar = Term,
         var_to_name(Bindings, Term, Name),
         Info = typed_var{name: Name, type: string}
+    ;   compound(Term), Term =.. [schema, SchemaName, Inner], var(Inner)
+    ->  % A declared shape: schema(name, Var)
+        BareVar = Inner,
+        var_to_name(Bindings, Inner, Name),
+        Info = typed_var{name: Name, type: object, schema: SchemaName}
     ;   compound(Term), Term =.. [Wrapper, Inner]
     ->  % Wrapped variable
         (   wrapper_type(Wrapper, Type)
@@ -317,6 +331,11 @@ extract_var_info(Bindings, Term, BareVar, Info) :-
             ->  BareVar = Inner,
                 var_to_name(Bindings, Inner, Name),
                 Info = typed_var{name: Name, type: Type}
+            ;   compound(Inner), Inner =.. [schema, SchemaName, InnerVar], var(InnerVar), Wrapper == list
+            ->  % List of declared shapes: list(schema(name, X))
+                BareVar = InnerVar,
+                var_to_name(Bindings, InnerVar, Name),
+                Info = typed_var{name: Name, type: array, itemType: object, schema: SchemaName}
             ;   compound(Inner), Inner =.. [InnerWrapper, InnerVar], var(InnerVar), Wrapper == list
             ->  % List of typed items: list(string(X))
                 BareVar = InnerVar,
@@ -431,6 +450,9 @@ clean_atomic(with_tools(Tools, Goal), with_tools(Tools, CleanGoal)) :-
 clean_atomic(without_tools(Tools, Goal), without_tools(Tools, CleanGoal)) :-
     !,
     clean_clause_body(Goal, CleanGoal).
+clean_atomic(with_fresh_memory(Goal), with_fresh_memory(CleanGoal)) :-
+    !,
+    clean_clause_body(Goal, CleanGoal).
 clean_atomic(with_judgment(Backend, Goal), with_judgment(Backend, CleanGoal)) :-
     !,
     clean_clause_body(Goal, CleanGoal).
@@ -742,8 +764,7 @@ process_directive(consult(File), SessionId) :-
     !,
     % Set session ID for get_session_id to find, then call our custom consult
     nb_setval(current_session_id, SessionId),
-    resolve_workspace_path(File, FullPath),
-    readutil:read_file_to_string(FullPath, Code, []),
+    system:read_file_to_string(File, Code, []),
     consult_string(Code, SessionId).
 %% Handle use_module directive
 process_directive(use_module(Module), SessionId) :-
@@ -766,7 +787,80 @@ process_directive([File|Files], SessionId) :-
     nb_setval(current_session_id, SessionId),
     process_directive(consult(File), SessionId),
     (Files == [] -> true ; process_directive(Files, SessionId)).
-process_directive(_, _).
+%% `:- repl_delete(Name/Arity).` — the directive form of the fact handled by
+%% process_clause/2 below. It used to fall through to the catch-all and be
+%% discarded, so a predicate the author asked to remove stayed in the module.
+process_directive(repl_delete(Name/Arity), SessionId) :-
+    !,
+    atom(Name),
+    integer(Arity),
+    Arity >= 0,
+    catch(abolish(SessionId:Name/Arity), _, true).
+
+%% process_directive(require_sandbox, +SessionId)
+%% The harness declares that it must run in an execution sandbox, and the load
+%% fails if it cannot. Checked against the **effective** backend rather than
+%% mere availability: bwrap being installed while the session resolves to
+%% clean-room means the code would run unsandboxed, which is what the directive
+%% exists to prevent. Only the user sets this (see repl_commit_directive/2).
+process_directive(require_sandbox, SessionId) :-
+    (   session_sandbox_backend(SessionId, Kind)
+    ->  true
+    ;   Kind = 'clean-room'
+    ),
+    (   sandbox_backend_acceptable(Kind)
+    ->  true
+    ;   format(atom(Message),
+            'harness requires an execution sandbox, but the effective backend is ~w; bwrap, AgentVM or sandbox-exec is required. Install bubblewrap, run with --sandbox (AgentVM), or remove the :- require_sandbox. directive.',
+            [Kind]),
+        throw(error(permission_error(load, harness, require_sandbox),
+                    context(require_sandbox/0, Message)))
+    ).
+
+%% Anything else is recorded rather than discarded. An unrecognised directive
+%% (`:- dynamic(f/1).`, a `:- op(...)` without use_module, a typo) does nothing,
+%% and silently doing nothing is how an edit that never took effect goes
+%% unnoticed. The host reports these after a load.
+process_directive(Directive, SessionId) :-
+    (   repl_benign_directive(Directive)
+    ->  true
+    ;   assertz(session_unhandled_directive(SessionId, Directive))
+    ).
+
+%% Directives DML deliberately accepts and ignores (SWI state it manages itself).
+repl_benign_directive(dynamic(_)).
+repl_benign_directive(dynamic(_, _)).
+repl_benign_directive(discontiguous(_)).
+repl_benign_directive(discontiguous(_, _)).
+repl_benign_directive(multifile(_)).
+repl_benign_directive(multifile(_, _)).
+
+%% sandbox_kind_atom(+Raw, -Atom)
+%% A JS string or an atom in, an atom out.
+%%
+%% Uses term_string/3, not atom_string/2: in this WASM build `atom_string/2`
+%% returns the string unchanged, so an "atom" produced by it still fails `atom/1`
+%% and compares unequal to every atom literal. That silently made every backend
+%% look unacceptable. `term_string(Atom, "bwrap", [])` does produce the atom.
+sandbox_kind_atom(Raw, Atom) :-
+    (   atom(Raw)
+    ->  Atom = Raw
+    ;   catch(term_string(Atom, Raw, []), _, Atom = Raw)
+    ).
+
+%% sandbox_backend_acceptable(+Kind)
+%% The backends that provide filesystem isolation for `exec(bash(...))`.
+%% `clean-room` is the absence of a wrapper and does not qualify. The host
+%% normalizes `sandbox-exec` to `sandbox_exec` (see DMLSession.open) because a
+%% hyphen makes the token a subtraction expression to a Prolog parser.
+sandbox_backend_acceptable(agentvm).
+sandbox_backend_acceptable(bwrap).
+sandbox_backend_acceptable(sandbox_exec).
+
+
+%% repl_unhandled_directives(+SessionId, -Directives)
+repl_unhandled_directives(SessionId, Directives) :-
+    findall(D, session_unhandled_directive(SessionId, D), Directives).
 
 %% ============================================================
 %% Engine Management
@@ -919,7 +1013,17 @@ create_session(SessionId, Params, HarnessMemory, MetaMemory) :-
     retractall(session_frozen(SessionId, _)),
     assertz(session_frozen(SessionId, false)),
     retractall(session_locked(SessionId, _)),
-    assertz(session_locked(SessionId, false)).
+    assertz(session_locked(SessionId, false)),
+    % Stored as an atom. The host sends a JS string, and an atom and a string
+    % that print identically are not `==`, so normalize once here rather than at
+    % every comparison.
+    (   get_dict(sandbox, Params, SandboxRaw)
+    ->  sandbox_kind_atom(SandboxRaw, SandboxKind)
+    ;   SandboxKind = 'clean-room'
+    ),
+    retractall(session_sandbox_backend(SessionId, _)),
+    assertz(session_sandbox_backend(SessionId, SandboxKind)),
+    repl_inject_workspace_predicates(SessionId).
 
 %% repl_abolish_user_predicates(+SessionId)
 %% Removes only the harness's own predicates; imported builtins are untouched.
@@ -1238,6 +1342,7 @@ internal_session_predicate(param).
 internal_session_predicate(param_decl).
 internal_session_predicate(tool_source).
 internal_session_predicate('__session__').
+internal_session_predicate(Name) :- workspace_predicate_name(Name).
 
 %% history_predicate(+Name)
 %% Runtime-owned harness-history facts. Excluded from the user predicate set (so
@@ -1267,6 +1372,7 @@ repl_reserved_name(repl_reserved_name).
 repl_reserved_name(repl_tool_catalog).
 repl_reserved_name(repl_listing).
 repl_reserved_name(repl_assert).
+repl_reserved_name(require_sandbox).
 repl_reserved_name(repl_retract).
 repl_reserved_name(repl_delete).
 repl_reserved_name(repl_freeze).
@@ -1502,12 +1608,11 @@ repl_script_files(SessionId, Paths) :-
 repl_materialize_embedded(SessionId) :-
     (   current_predicate(SessionId:embedded_file/2)
     ->  forall(SessionId:embedded_file(Path, Content),
-            (   resolve_workspace_path(Path, Full),
-                catch(
-                    (   file_directory_name(Full, Dir),
+            (   catch(
+                    (   file_directory_name(Path, Dir),
                         make_directory_path(Dir),
                         setup_call_cleanup(
-                            open(Full, write, Stream),
+                            open(Path, write, Stream),
                             format(Stream, "~s", [Content]),
                             close(Stream))
                     ),
@@ -1604,6 +1709,8 @@ repl_assert(SessionId, ClauseText, Result) :-
     catch(
         (   guard_not_frozen(SessionId),
             repl_prepare_single(SessionId, ClauseText, PreparedTerms),
+            forall(member(PreparedTerm, PreparedTerms),
+                repl_require_new_predicate(SessionId, PreparedTerm)),
             forall(member(PreparedTerm, PreparedTerms),
                 repl_assert_clause(PreparedTerm, SessionId)),
             Result = ok
@@ -1663,11 +1770,25 @@ repl_read_prepared_terms(Stream, SessionId, Terms) :-
         % their operators are visible to the terms that follow; keep them out of
         % the returned list so repl_commit_terms does not process them twice.
         partition_directives(Prepared, Rules, Directives),
-        forall(member(Directive, Directives), process_clause(Directive, SessionId)),
+        forall(member(Directive, Directives), repl_commit_directive(Directive, SessionId)),
         append(Rules, Rest, Terms),
         repl_read_prepared_terms(Stream, SessionId, Rest)
     ).
 
+%% repl_commit_directive(+Directive, +SessionId)
+%% Directives written by the *agent* (assert_many/define) run here. `require_sandbox`
+%% is the user's to set — through `/set-require-sandbox` — so an agent cannot
+%% declare a requirement it was not asked for, nor lift one by re-asserting the
+%% harness. The file-load path (parse_clauses/2) is deliberately not guarded:
+%% that is what the user's own harness file goes through.
+repl_commit_directive((:- require_sandbox), _SessionId) :-
+    !,
+    throw(error(permission_error(modify, reserved_name, require_sandbox),
+                context(repl_commit_directive/2,
+                        'only the user can set the sandbox requirement'))).
+repl_commit_directive(Directive, SessionId) :-
+    process_clause(Directive, SessionId).
+
 partition_directives([], [], []).
 partition_directives([Term|Terms], Rules, Directives) :-
     (   Term = (:- _)
@@ -1696,6 +1817,9 @@ repl_assert_many(SessionId, ClausesText, Result) :-
     catch(
         (   guard_not_frozen(SessionId),
             repl_parse_clauses(SessionId, ClausesText, Terms),
+            % assert appends; against an existing predicate that leaves both
+            % versions live with their clauses interleaved.
+            forall(member(Term, Terms), repl_require_new_predicate(SessionId, Term)),
             repl_commit_terms(SessionId, Terms),
             repl_note_touched(SessionId, Terms),
             Result = ok
@@ -1719,11 +1843,105 @@ repl_term_indicator(Term, Name/Arity) :-
 %% Record the predicate indicators a term list defines, for history recording.
 repl_note_touched(SessionId, Terms) :-
     forall(( member(Term, Terms), repl_term_indicator(Term, Name/Arity) ),
-        (   session_edit_touched(SessionId, Name/Arity)
-        ->  true
-        ;   assertz(session_edit_touched(SessionId, Name/Arity))
+        repl_note_indicator(SessionId, Name/Arity)).
+
+repl_note_indicator(SessionId, Name/Arity) :-
+    (   session_edit_touched(SessionId, Name/Arity)
+    ->  true
+    ;   assertz(session_edit_touched(SessionId, Name/Arity))
+    ).
+
+%% repl_require_new_predicate(+SessionId, +Term)
+%% `assert`/`assert_many` append. Against a predicate that already has clauses
+%% that mixes the old and the new version — both stay live, clause order
+%% interleaves them, and nothing says so. Refuse instead, and name the remedy.
+repl_require_new_predicate(SessionId, Term) :-
+    repl_term_indicator(Term, Name/Arity),
+    findall(x,
+        (   functor(Head, Name, Arity),
+            clause(SessionId:Head, _)
+        ),
+        Existing),
+    Existing \== [],
+    !,
+    length(Existing, Count),
+    format(atom(Message),
+        '~w/~w already has ~w clause(s). assert appends, so the old and the new clauses would both be present and clause order would interleave them. Use define("~w/~w", "...") to replace the predicate, or delete("~w/~w") first.',
+        [Name, Arity, Count, Name, Arity, Name, Arity]),
+    throw(error(permission_error(modify, existing_predicate, Name/Arity),
+                context(repl_require_new_predicate/2, Message))).
+repl_require_new_predicate(_SessionId, _Term).
+
+%% repl_forget_tool(+SessionId, +Name)
+%% Drop the tool annotation that belonged to a predicate being removed.
+repl_forget_tool(SessionId, Name) :-
+    (   session_user_tools(SessionId, Name)
+    ->  retractall(session_user_tools(SessionId, Name)),
+        retractall(session_user_tool_schema(SessionId, Name, _)),
+        catch(retractall(SessionId:tool_source(Name, _)), _, true)
+    ;   true
+    ).
+
+%% repl_capture_predicates(+SessionId, +Indicators, -Captured)
+%% Copy the clauses and tool bookkeeping a replacement is about to destroy, so
+%% a failure part-way through can put them back.
+repl_capture_predicates(SessionId, Indicators, Captured) :-
+    findall(indicator(Name, Arity, Clauses, tool(IsTool, Schema, Source)),
+        (   member(Name/Arity, Indicators),
+            findall(Stored,
+                (   functor(Head, Name, Arity),
+                    clause(SessionId:Head, Body),
+                    (   Body == true
+                    ->  Stored = Head
+                    ;   Stored = (Head :- Body)
+                    )
+                ),
+                Clauses),
+            (   session_user_tools(SessionId, Name)
+            ->  IsTool = true
+            ;   IsTool = false
+            ),
+            (   session_user_tool_schema(SessionId, Name, Found)
+            ->  Schema = Found
+            ;   Schema = none
+            ),
+            (   current_predicate(SessionId:tool_source/2),
+                SessionId:tool_source(Name, FoundSource)
+            ->  Source = FoundSource
+            ;   Source = none
+            )
+        ),
+        Captured).
+
+%% repl_restore_captured(+SessionId, +Captured)
+repl_restore_captured(SessionId, Captured) :-
+    forall(member(indicator(Name, Arity, Clauses, tool(IsTool, Schema, Source)), Captured),
+        (   catch(abolish(SessionId:Name/Arity), _, true),
+            repl_forget_tool(SessionId, Name),
+            forall(member(Clause, Clauses), assertz(SessionId:Clause)),
+            (   IsTool == true
+            ->  assertz(session_user_tools(SessionId, Name))
+            ;   true
+            ),
+            (   Schema == none
+            ->  true
+            ;   assertz(session_user_tool_schema(SessionId, Name, Schema))
+            ),
+            (   Source == none
+            ->  true
+            ;   assertz(SessionId:tool_source(Name, Source))
+            )
         )).
 
+%% repl_replace_predicates(+SessionId, +Indicators, +Terms)
+%% The destructive half of define: abolish the targets, then assert the block.
+repl_replace_predicates(SessionId, Indicators, Terms) :-
+    forall(member(Name/Arity, Indicators),
+        (   catch(abolish(SessionId:Name/Arity), _, true),
+            repl_forget_tool(SessionId, Name)
+        )),
+    repl_commit_terms(SessionId, Terms).
+
 %% repl_edit_touched(+SessionId, -Indicators)
 %% Predicates touched by edit tools since the last clear (sorted, unique).
 repl_edit_touched(SessionId, Indicators) :-
@@ -1754,7 +1972,13 @@ repl_system_functor(Name/_) :-
     member(Name, ['.', ',', ';', ':-', '->', ':', '|', '!', '\\+', '=', 'is']).
 
 %% repl_retract(+SessionId, +ClausePattern, -Result)
-%% Retracts matching user clauses. Reserved names are protected.
+%% Removes the clauses that match the pattern, and says how many.
+%%
+%% This used to build a fresh head with `functor/3` and call `retractall/1`, so
+%% the pattern's *arguments were discarded*: `retract("g(1)")` removed every
+%% g/1 clause and reported `ok`. It now retracts what was asked for, and fails
+%% loudly when nothing matched — a silent no-op is how an agent concludes a
+%% clause is gone when it never was.
 repl_retract(SessionId, ClauseText, Result) :-
     catch(
         (   guard_not_frozen(SessionId),
@@ -1766,19 +1990,29 @@ repl_retract(SessionId, ClauseText, Result) :-
                         context(repl_retract/3, 'cannot retract a reserved predicate')))
             ;   true
             ),
-            functor(Head, Name, Arity),
-            retractall(SessionId:Head),
-            (   session_user_tools(SessionId, Name)
-            ->  retractall(session_user_tools(SessionId, Name)),
-                retractall(session_user_tool_schema(SessionId, Name, _)),
-                retractall(SessionId:tool_source(Name, _))
+            findall(x, retract(SessionId:Pattern), Removed),
+            length(Removed, RemovedCount),
+            (   RemovedCount =:= 0
+            ->  format(atom(Message),
+                    'no clause of ~w/~w matched ~w, so nothing was removed',
+                    [Name, Arity, Clause]),
+                throw(error(existence_error(clause, Clause),
+                            context(repl_retract/3, Message)))
             ;   true
             ),
-            (   session_edit_touched(SessionId, Name/Arity)
+            % Only drop the tool annotation when the predicate is really gone;
+            % other clauses of it may still be live.
+            (   functor(Head, Name, Arity),
+                clause(SessionId:Head, _)
             ->  true
-            ;   assertz(session_edit_touched(SessionId, Name/Arity))
+            ;   repl_forget_tool(SessionId, Name)
             ),
-            Result = ok
+            repl_note_indicator(SessionId, Name/Arity),
+            (   RemovedCount =:= 1
+            ->  Suffix = ''
+            ;   Suffix = 's'
+            ),
+            format(atom(Result), 'ok(removed ~w clause~w)', [RemovedCount, Suffix])
         ),
         RetractError,
         format(atom(Result), 'error(~w)', [RetractError])
@@ -1814,34 +2048,45 @@ repl_delete_predicate(SessionId, Name, Arity, Result) :-
     ).
 
 %% repl_define(+SessionId, +HeadPatternText, +ClausesText, -Result)
-%% Replace every predicate the clause block defines. It parses the block,
-%% computes its indicators (plus the head pattern's), abolishes each, then
-%% asserts the block. This makes `define` safe no matter how many predicates a
-%% block spans, so a multi-predicate block cannot append duplicate clauses.
+%% Replace every predicate the clause block defines, all or nothing.
+%%
+%% The order matters and used to be wrong. Abolishing first and asserting after
+%% means any failure in between leaves the target *destroyed*: a block with one
+%% reserved name in it removed the predicate it was replacing and reported an
+%% error, and a following `end_turn` then committed the deletion as a version.
+%% So everything that can fail is checked before anything is touched, and the
+%% clauses being replaced are copied first so a failure can still put them back.
 repl_define(SessionId, HeadPatternText, ClausesText, Result) :-
     catch(
         (   guard_not_frozen(SessionId),
-            repl_read_clause(SessionId, HeadPatternText, Pattern),
-            repl_head_of(Pattern, HeadClause),
-            repl_callable_indicator(HeadClause, HeadName, HeadArity),
+            repl_define_target(SessionId, HeadPatternText, HeadName, HeadArity),
             repl_parse_clauses(SessionId, ClausesText, Terms),
             findall(Name/Arity,
                 ( member(Term, Terms), repl_term_indicator(Term, Name/Arity) ),
                 BlockIndicators0),
-            sort([HeadName/HeadArity|BlockIndicators0], Indicators),
-            forall(member(Name/Arity, Indicators),
-                (   repl_protected_name(Name)
-                ->  throw(error(permission_error(modify, reserved_name, Name/Arity),
-                            context(repl_define/4, 'cannot define a reserved predicate')))
-                ;   catch(abolish(SessionId:Name/Arity), _, true),
-                    (   session_user_tools(SessionId, Name)
-                    ->  retractall(session_user_tools(SessionId, Name)),
-                        retractall(session_user_tool_schema(SessionId, Name, _)),
-                        retractall(SessionId:tool_source(Name, _))
-                    ;   true
-                    )
-                )),
-            repl_commit_terms(SessionId, Terms),
+            sort(BlockIndicators0, BlockIndicators),
+            % The head names the predicate being replaced. If it is not one of
+            % them the target is almost certainly a typo, and silently replacing
+            % a *different* predicate is worse than refusing.
+            (   BlockIndicators \== [],
+                \+ member(HeadName/HeadArity, BlockIndicators)
+            ->  format(atom(TargetMessage),
+                    'define was told to replace ~w/~w, but the clause block defines ~w. Pass the predicate you are replacing as the head.',
+                    [HeadName, HeadArity, BlockIndicators]),
+                throw(error(domain_error(define_target, HeadName/HeadArity),
+                            context(repl_define/4, TargetMessage)))
+            ;   true
+            ),
+            sort([HeadName/HeadArity|BlockIndicators], Indicators),
+            % Validate everything that can fail, before anything is removed.
+            forall(member(Term, Terms), repl_require_committable(SessionId, Term)),
+            forall(member(Name/Arity, Indicators), repl_require_not_reserved(SessionId, Name/Arity)),
+            repl_capture_predicates(SessionId, Indicators, Captured),
+            (   catch(repl_replace_predicates(SessionId, Indicators, Terms), ReplaceError,
+                    (   repl_restore_captured(SessionId, Captured),
+                        throw(ReplaceError)
+                    ))
+            ),
             repl_note_touched(SessionId, Terms),
             Result = ok
         ),
@@ -1849,6 +2094,42 @@ repl_define(SessionId, HeadPatternText, ClausesText, Result) :-
         format(atom(Result), 'error(~w)', [DefineError])
     ).
 
+%% repl_define_target(+SessionId, +HeadText, -Name, -Arity)
+%% The first argument of `define` names the predicate being replaced, written as
+%% an indicator (`f/1`) or as a clause head (`f(_)`).
+%%
+%% It has to be decomposed explicitly: `f/1` *reads* as the operator term
+%% `/(f, 1)`, so treating it as a clause head yields the functor `//2`. That is
+%% what used to happen — the target was silently ignored and the clause block
+%% alone decided what got replaced, so `define` accepted any name at all.
+repl_define_target(SessionId, HeadText, Name, Arity) :-
+    repl_read_clause(SessionId, HeadText, Pattern),
+    (   Pattern = IndicatorName/IndicatorArity,
+        atom(IndicatorName),
+        integer(IndicatorArity),
+        IndicatorArity >= 0
+    ->  Name = IndicatorName,
+        Arity = IndicatorArity
+    ;   repl_head_of(Pattern, HeadClause),
+        repl_callable_indicator(HeadClause, Name, Arity)
+    ).
+
+%% repl_require_committable(+SessionId, +Term)
+repl_require_committable(_SessionId, Term) :-
+    (   repl_protected_clause(Term)
+    ->  throw(error(permission_error(modify, reserved_name, Term),
+                context(repl_define/4, 'cannot define a reserved predicate')))
+    ;   true
+    ).
+
+%% repl_require_not_reserved(+SessionId, +Indicator)
+repl_require_not_reserved(_SessionId, Name/Arity) :-
+    (   repl_protected_name(Name)
+    ->  throw(error(permission_error(modify, reserved_name, Name/Arity),
+                context(repl_define/4, 'cannot define a reserved predicate')))
+    ;   true
+    ).
+
 %% repl_extract_code(+Text, -Source)
 %% Extracts a ```dml fenced block; falls back to the whole answer.
 repl_extract_code(Text, Source) :-
@@ -2103,6 +2384,80 @@ repl_predicate_pure(SessionId, Name, Arity) :-
     functor(Head, Name, Arity),
     \+ ( clause(SessionId:Head, Body), repl_body_impure(Body) ).
 
+%% ============================================================
+%% Tool contract validation (end_turn advisory)
+%% ============================================================
+%%
+%% A tool head is what the nested agent calls; the tool body is what runs. So a
+%% well-formed tool is `tool(foo(A,B), "…") :- foo(A,B)` with foo/2 defined
+%% separately. The declared head arrives structurally through `clause/2` (its
+%% body is NOT executed), so a declared-but-undefined tool is caught here rather
+%% than at call time deep inside a nested agent.
+%%
+%% Known limitation: a module-qualified skill delegate (e.g. `other:solve(A,B)`)
+%% is not a session predicate and is reported; use `with_tools/2` for those.
+
+%% repl_validate_tools(+SessionId, -Warnings)
+repl_validate_tools(SessionId, Warnings) :-
+    findall(W, tool_contract_violation(SessionId, W), Raw),
+    list_to_set(Raw, Warnings).
+
+%% repl_validate_docs(+SessionId, -Warnings)
+%%
+%% `doc(Name/Arity, Text)` is an annotation: it documents a predicate, it does not
+%% create one. A `doc/2` whose predicate has no clauses therefore names a goal that
+%% fails silently when called — the failure surfaces far away as an empty result,
+%% and the name still appears in the manifest, so the listing looks healthy.
+%% Reported at `end_turn`, where the author can still see what they just wrote.
+repl_validate_docs(SessionId, Warnings) :-
+    findall(W, doc_without_clauses(SessionId, W), Raw),
+    list_to_set(Raw, Warnings).
+
+doc_without_clauses(SessionId, Warning) :-
+    SessionId:doc(Name/Arity, _),
+    (   \+ current_predicate(SessionId:Name/Arity)
+    ;   functor(Head, Name, Arity),
+        \+ clause(SessionId:Head, _)
+    ),
+    !,
+    format(string(Warning),
+        'doc(~w/~w) documents a predicate with no clauses, so calling it fails silently and yields an empty result. Define ~w/~w, or remove the doc/2.',
+        [Name, Arity, Name, Arity]).
+
+tool_contract_violation(SessionId, Warning) :-
+    clause(SessionId:tool(Head), Body),
+    compound(Head),
+    Head =.. [Name|HeadArgs],
+    length(HeadArgs, Arity),
+    tool_body_goal(Body, Call),
+    Call =.. [Callee|Args],
+    length(Args, CalleeArity),
+    (   Callee == Name, CalleeArity == Arity, \+ repl_user_predicate(SessionId, Name, Arity)
+    ->  format(string(Warning),
+            'tool ~w/~w calls the tool itself, so a nested agent recurses forever. Define ~w/~w separately and delegate to it: tool(~w(A,B), "…") :- ~w(A,B).',
+            [Name, Arity, Name, Name, Name, Name])
+    ;   Callee == Name, CalleeArity \== Arity
+    ->  format(string(Warning),
+            'tool ~w/~w declares a different arity than its body calls (~w/~w). A tool head and its delegate must match, with the output argument last.',
+            [Name, Arity, Callee, CalleeArity])
+    ;   \+ ( SessionId:current_predicate(Callee/CalleeArity) )
+    ->  format(string(Warning),
+            'tool ~w/~w calls ~w/~w, which is not defined, so a nested agent gets "Tool not found". Define ~w/~w and delegate to it.',
+            [Name, Arity, Callee, CalleeArity, Callee, CalleeArity])
+    ).
+
+%% tool_body_goal(+Body, -FirstCall): a tool body must reach a call, not be empty.
+tool_body_goal(Body, Call) :-
+    Body \== true,
+    tool_first_goal(Body, Call),
+    compound(Call),
+    functor(Call, F, _),
+    F \== (',').
+
+%% tool_first_goal(+Body, -Call): the first call in a conjunction body.
+tool_first_goal((A, _), Call) :- !, tool_first_goal(A, Call).
+tool_first_goal(Call, Call).
+
 %% True when the predicate has at least one clause with a real body (not a fact).
 repl_predicate_has_rule(SessionId, Name, Arity) :-
     functor(Head, Name, Arity),
@@ -3313,7 +3668,8 @@ mi_call_prompt_n(Desc, Vars, VarNames, StateIn, StateOut) :-
     add_trace_entry(SessionId, llm_call, prompt, [InterpDesc], Depth),
     % prompt/N is a simple LLM call - no tools, no tool scope
     get_model_spec(StateIn, ModelSpec),
-    engine_yield(request_agent_loop(InterpDesc, VarNames, [], [], none, ModelSpec)),
+    resolve_schema_fields(SessionId, VarNames, ResolvedVarNames),
+    engine_yield(request_agent_loop(InterpDesc, ResolvedVarNames, [], [], none, ModelSpec)),
     % Wait for agent_done (no tool calls expected since no tools provided)
     handle_agent_signals(SessionId, StateIn, StateOut),
     session_agent_result(SessionId, Result),
@@ -3331,7 +3687,7 @@ mi_call_prompt_n(Desc, Vars, VarNames, StateIn, StateOut) :-
         engine_yield(output(WarnMsg)),
         fail
     ),
-    bind_task_variables(Result.variables, VarNames, Vars).
+    bind_task_variables(SessionId, Result.variables, VarNames, Vars).
     % Don't modify memory - but state may have changed from tool calls
 
 mi_call_sample_token(Desc, Allowed, Token, StateIn, StateOut) :-
@@ -3594,7 +3950,8 @@ mi_call_task_n(Desc, Vars, VarNames, StateIn, StateOut) :-
     get_reasoning_effort(StateIn, ReasoningEffort),
     get_recipe_context(StateIn, RecipeContext),
     get_model_spec(StateIn, ModelSpec),
-    engine_yield(request_agent_loop(InterpDesc, VarNames, UserTools, Memory, ToolScope, ReasoningEffort, RecipeContext, ModelSpec)),
+    resolve_schema_fields(SessionId, VarNames, ResolvedVarNames),
+    engine_yield(request_agent_loop(InterpDesc, ResolvedVarNames, UserTools, Memory, ToolScope, ReasoningEffort, RecipeContext, ModelSpec)),
     % Handle signals (tool calls) until agent_done
     handle_agent_signals(SessionId, StateIn, StateAfterAgent),
     session_agent_result(SessionId, Result),
@@ -3611,7 +3968,7 @@ mi_call_task_n(Desc, Vars, VarNames, StateIn, StateOut) :-
         engine_yield(output(WarnMsg)),
         fail
     ),
-    bind_task_variables(Result.variables, VarNames, Vars),
+    bind_task_variables(SessionId, Result.variables, VarNames, Vars),
     % Use full memory from agent loop result when available
     (   get_dict(full_memory, Result, FullMemory), is_list(FullMemory)
     ->  set_memory(StateAfterAgent, FullMemory, StateOut),
@@ -3633,18 +3990,134 @@ mi_call_task_n(Desc, Vars, VarNames, StateIn, StateOut) :-
         )
     ).
 
+%% ---------------------------------------------------------------
+%% Output schemas: schema(Name, [field(Field, Type, Option), ...])
+%%
+%% `list(object(B))` says "a list of dicts" but not what is in them, so every
+%% harness re-derives defaults and tolerates missing fields by hand. A schema
+%% declares the shape once, and `schema_fill/3` makes the value match it: absent
+%% fields with a default are filled, unknown fields are kept (so a model mistake
+%% stays visible rather than disappearing), and a `required` field that is absent
+%% or a field of the wrong type **fails the step** rather than yielding an empty
+%% result.
+%%
+%%   schema(author, [
+%%       field(name,        string, required),
+%%       field(affiliation, string, default("not stated")),
+%%       field(email,       string, default(""))
+%%   ]).
+%%
+%%   task("From the front matter extract every author: {Text}",
+%%        list(schema(author, Authors))).
+%% schema_fill(+Fields, +Value, -Filled): the pure part, so it is testable and
+%% usable without a session. The session predicate schema_fill/3 looks the fields
+%% up from `schema/2`.
+schema_fill_fields(Fields, Value, Filled) :-
+    is_dict(Value),
+    (   member(field(Field, Type, required), Fields),
+        \+ dict_field(Value, Field, _),
+        !,
+        format(atom(Msg), 'schema: required field "~w" is missing', [Field]),
+        throw(error(schema_error(Msg), schema_fill/3))
+    ;   true
+    ),
+    (   member(field(Field, Type, _), Fields),
+        dict_field(Value, Field, Found),
+        \+ schema_value_ok(Type, Found),
+        !,
+        format(atom(Msg), 'schema: field "~w" is not ~w (~w)', [Field, Type, Found]),
+        throw(error(schema_error(Msg), schema_fill/3))
+    ;   true
+    ),
+    dict_pairs(Value, _, Pairs),
+    findall(Key-NewValue,
+        (   member(Key-Old, Pairs),
+            (   member(field(Key, _, Option), Fields)
+            ->  (   Option = default(Default), Old == "" -> NewValue = Default
+                ;   NewValue = Old
+                )
+            ;   NewValue = Old          % undeclared: kept, so it stays visible
+            )
+        ),
+        Updated),
+    findall(Field-Default,
+        (   member(field(Field, _, default(Default)), Fields),
+            \+ dict_field(Value, Field, _)
+        ),
+        Missing),
+    append(Updated, Missing, All),
+    dict_pairs(Filled, _, All).
+
+%% A declared type accepts its own shape; anything coarser (a number for a string
+%% field, for instance) fails, because silently coercing hides the model's error.
+schema_value_ok(string, V) :- ( string(V) ; atom(V) ), !.
+schema_value_ok(integer, V) :- integer(V), !.
+schema_value_ok(number, V) :- number(V), !.
+schema_value_ok(boolean, V) :- ( V == true ; V == false ; V == yes ; V == no ), !.
+schema_value_ok(object, V) :- is_dict(V), !.
+schema_value_ok(array, V) :- is_list(V), !.
+schema_value_ok(_, _) :- fail.
+
 %% bind_task_variables(+VarsDict, +Names, -Values)
-bind_task_variables(_, [], []) :- !.
-bind_task_variables(VarsDict, [N|Names], [Value|Values]) :-
+bind_task_variables(_, _, [], []) :- !.
+bind_task_variables(SessionId, VarsDict, [N|Names], [Value|Values]) :-
     (   is_dict(N)
     ->  Key = N.name
     ;   Key = N
     ),
-    (   get_dict(Key, VarsDict, Value)
+    (   get_dict(Key, VarsDict, Raw)
     ->  true
-    ;   true
+    ;   Raw = _Missing
+    ),
+    (   is_dict(N), get_dict(schema, N, SchemaName), nonvar(Raw)
+    ->  schema_fields_of(SessionId, SchemaName, Fields),
+        (   is_list(Raw)
+        ->  maplist(schema_filled(Fields), Raw, Value)
+        ;   schema_fill_fields(Fields, Raw, Value)
+        )
+    ;   Value = Raw
     ),
-    bind_task_variables(VarsDict, Names, Values).
+    bind_task_variables(SessionId, VarsDict, Names, Values).
+
+schema_fields_of(SessionId, Name, Fields) :-
+    (   catch(clause(SessionId:schema(Name, Fields), true), _, fail)
+    ->  true
+    ;   format(atom(Msg), 'schema "~w" is not declared', [Name]),
+        throw(error(schema_error(Msg), schema_fields_of/3))
+    ).
+
+%% resolve_schema_fields(+SessionId, +VarNames, -Resolved)
+%%
+%% Attach a schema's field list to the descriptor for each output variable that
+%% names one, so the agent building the prompt can tell the model the shape to
+%% produce. Done here rather than in extract_var_info/4 (which runs at load time)
+%% because the `schema/2` fact is only certainly present once everything is loaded.
+resolve_schema_fields(SessionId, VarNames, Resolved) :-
+    maplist(resolve_schema_field(SessionId), VarNames, Resolved).
+
+resolve_schema_field(SessionId, VarName, Resolved) :-
+    (   is_dict(VarName), get_dict(schema, VarName, SchemaName)
+    ->  (   schema_field_dicts(SessionId, SchemaName, Fields)
+        ->  put_dict(fields, VarName, Fields, Resolved)
+        ;   Resolved = VarName
+        )
+    ;   Resolved = VarName
+    ).
+
+%% Field descriptors as dicts, so they cross the bridge without a decoder.
+%% `required` is 1/0 rather than an atom: the atom `false` arrives as the string
+%% "false", which is truthy in JavaScript.
+schema_field_dicts(SessionId, SchemaName, Dicts) :-
+    catch(clause(SessionId:schema(SchemaName, Fields), true), _, fail),
+    findall(x{name: Field, type: Type, required: Required, default: Default},
+        (   member(field(Field, Type, Option), Fields),
+            (   Option == required -> Required = 1 ; Required = 0 ),
+            (   Option = default(D) -> Default = D ; Default = no_default )
+        ),
+        Dicts).
+
+schema_filled(Fields, Raw, Filled) :-
+    (   is_dict(Raw) -> schema_fill_fields(Fields, Raw, Filled) ; Filled = Raw ).
 
 %% ============================================================
 %% Exec Handling
@@ -3692,6 +4165,19 @@ mi_call(with_tools(ToolList, Goal), StateIn, StateOut) :-
     mi_call(Goal, ScopedState, StateWithScope),
     clear_tool_scope(StateWithScope, StateOut).
 
+%% mi_call(with_fresh_memory(Goal), +StateIn, -StateOut)
+%% Run Goal with an empty memory, and discard whatever it accumulates. The steps
+%% inside see nothing from the caller, and the caller sees nothing from them.
+%% Use it to scope a group of task/N calls that must not be influenced by the
+%% conversation so far, or to keep a long history from growing through a
+%% sub-computation. `prompt/N` is the single-call equivalent.
+mi_call(with_fresh_memory(Goal), StateIn, StateOut) :-
+    !,
+    get_memory(StateIn, SavedMemory),
+    set_memory(StateIn, [], FreshState),
+    mi_call(Goal, FreshState, AfterGoal),
+    set_memory(AfterGoal, SavedMemory, StateOut).
+
 %% mi_call(without_tools(ToolList, Goal), +StateIn, -StateOut)
 %% Run Goal with the specified tools excluded from nested tasks
 mi_call(without_tools(ToolList, Goal), StateIn, StateOut) :-
@@ -3786,15 +4272,12 @@ mi_call(save_image(Media, Out), StateIn, StateIn) :-
     media_dict(Media, Dict),
     (   get_dict(kind, Dict, inline_svg),
         get_dict(data, Dict, Svg)
-    ->  resolve_workspace_path(Out, OutAbs),
-        open(OutAbs, write, Stream),
+    ->  open(Out, write, Stream),
         write(Stream, Svg),
         close(Stream)
     ;   get_dict(path, Dict, Path),
         Path \== ""
-    ->  resolve_workspace_path(Path, InAbs),
-        resolve_workspace_path(Out, OutAbs),
-        copy_file(InAbs, OutAbs)
+    ->  copy_file(Path, Out)
     ;   throw(error(domain_error(save_image, Media), save_image/2))
     ).
 
@@ -4284,28 +4767,428 @@ mi_foldl(Goal, [H|T], V0, V, StateIn, StateOut) :-
     mi_foldl(Goal, T, V1, V, State1, StateOut).
 
 %% ============================================================
-%% File I/O - All paths relative to /workspace
+%% Workspace predicates (one definition, every surface)
 %% ============================================================
+%%
+%% These are **real clauses in the session module**, not only meta-interpreter
+%% handlers. `read_file/2` in particular has no other definition in this build:
+%% without these clauses it exists only as an `mi_call/3` body, so it works from
+%% DML but fails from a host query. Installing them makes a host query, `execute`,
+%% `/goal` and a nested `task/N` resolve the same predicate.
+%%
+%% The file-stream primitives live in `system:` (NOT `readutil`, which has no
+%% `read_file_to_string/3`). They are module-qualified so a wrapper cannot
+%% recurse into itself.
+%%
+%% Deliberately not here: `open/3`, `close/1`, `read_string/3`, `write/2`. They
+%% are imported builtins in the session module and SWI refuses to shadow an
+%% imported private predicate, so a workspace-resolving version cannot be
+%% installed. `read_file/2` and `write_file/2` are the whole-file API instead.
+%%
+%% `workspace_predicate_name/1` is the single source of truth; it also keeps the
+%% set out of `listing` / `export` / history.
+
+workspace_predicate_name(read_file).
+workspace_predicate_name(read_file_to_string).
+workspace_predicate_name(write_file).
+workspace_predicate_name(append_file).
+workspace_predicate_name(exists_file).
+workspace_predicate_name(exists_directory).
+workspace_predicate_name(directory_files).
+workspace_predicate_name(make_directory).
+workspace_predicate_name(make_directory_path).
+workspace_predicate_name(delete_file).
+workspace_predicate_name(delete_directory).
+workspace_predicate_name(size_file).
+workspace_predicate_name(time_file).
+workspace_predicate_name(dict_field).
+workspace_predicate_name(dict_field_key).
+workspace_predicate_name(json_get).
+workspace_predicate_name(json_gets).
+workspace_predicate_name(json_put).
+workspace_predicate_name(json_text).
+workspace_predicate_name(schema_fill).
+workspace_predicate_name(pattern).
+
+%% dict_field(+Dict, +Key, -Value) and dict_field(+Dict, +Key, +Default, -Value)
+%%
+%% Look up a field of a model-produced dict. SWI dicts have *atom* keys and
+%% `get_dict/3` is strict: `get_dict("affiliation", D)` raises
+%% `type_error(dict-key, affiliation)` rather than failing, and the model varies
+%% the spelling (`Name` / `name` / `full_name`). This matches on a normalised
+%% atom — any of atom/string, any case, `_`/`-`/space ignored — so
+%% `dict_field(D, "affiliation", A)` finds the `affiliation` key.
+dict_field(Dict, Key, Value) :-
+    is_dict(Dict),
+    dict_field_key(Key, Wanted),
+    dict_pairs(Dict, _, Pairs),
+    member(K-V, Pairs),
+    dict_field_key(K, Wanted),
+    Value = V.
+
+dict_field(Dict, Key, Default, Value) :-
+    (   dict_field(Dict, Key, Found)
+    ->  Value = Found
+    ;   Value = Default
+    ).
+
+%% dict_field_key(+Key, -Normalised): lowercase atom with separators removed.
+dict_field_key(Key, Normalised) :-
+    (   atom(Key) -> atom_string(Key, Text) ; Text = Key ),
+    string_lower(Text, Lower),
+    split_string(Lower, " _-", "", Parts),
+    atomic_list_concat(Parts, '', Normalised).
+
+%% json_get/3,4, json_gets/3, json_put/4, json_text/2
+%%
+%% Path access into a model-produced structure, so a nested lookup is one call
+%% rather than a chain of dict_field/3. A path is a list of keys and indices, or a
+%% string/atom with `.` separators (`"results.0.authors.1.name"`), which is how a
+%% JSON path is normally written.
+%%
+%% A missing path **fails** — it does not throw and does not yield "" — so absence
+%% is visible at the call site; json_get/4 supplies a default instead. Key matching
+%% is the same tolerant match as dict_field/3 (atom or string, any case,
+%% `_`/`-`/space ignored).
+json_path_segments(Path, Segments) :-
+    (   is_list(Path)
+    ->  Segments = Path
+    ;   (   atom(Path) -> atom_string(Path, Text) ; Text = Path ),
+        split_string(Text, ".", "", RawParts),
+        exclude(==(""), RawParts, Parts),
+        maplist(json_path_segment, Parts, Segments)
+    ).
+
+json_path_segment("*", star) :- !.
+json_path_segment(Part, Index) :-
+    catch(number_string(N, Part), _, fail),
+    integer(N),
+    !,
+    Index = N.
+json_path_segment(Part, Part).
+
+%% json_walk(+Value, +Segments, -Found)
+json_walk(Value, [], Value) :- !.
+json_walk(Doc, [Index|Rest], Found) :-
+    integer(Index),
+    is_list(Doc),
+    !,
+    nth0(Index, Doc, Next),
+    json_walk(Next, Rest, Found).
+json_walk(Doc, [Key|Rest], Found) :-
+    is_dict(Doc),
+    dict_field_key(Key, Wanted),
+    dict_pairs(Doc, _, Pairs),
+    member(K-V, Pairs),
+    dict_field_key(K, Wanted),
+    json_walk(V, Rest, Found).
+
+json_get(Doc, Path, Value) :-
+    json_path_segments(Path, Segments),
+    \+ member(star, Segments),
+    json_walk(Doc, Segments, Value).
+
+json_get(Doc, Path, Default, Value) :-
+    (   json_get(Doc, Path, Found)
+    ->  Value = Found
+    ;   Value = Default
+    ).
+
+%% json_gets/3: `*` maps over a list, collecting the remainder for every element.
+%% Nested `*`s flatten, so "results.*.authors.*.name" is a flat list of names.
+json_gets(Doc, Path, Values) :-
+    json_path_segments(Path, Segments),
+    json_collect(Doc, Segments, Values).
+
+json_collect(Value, [], [Value]) :- !.
+json_collect(Doc, [star|Rest], Values) :-
+    is_list(Doc),
+    findall(Collected,
+        ( member(Item, Doc), json_collect(Item, Rest, Collected) ),
+        Nested),
+    append(Nested, Values).
+json_collect(Doc, [Seg|Rest], Values) :-
+    json_walk_1(Doc, Seg, Next),
+    json_collect(Next, Rest, Values).
+
+%% One step of a walk, for the collector (where `star` is handled by the caller).
+json_walk_1(Doc, Index, Value) :- integer(Index), is_list(Doc), !, nth0(Index, Doc, Value).
+json_walk_1(Doc, Key, Value) :-
+    is_dict(Doc),
+    dict_field_key(Key, Wanted),
+    dict_pairs(Doc, _, Pairs),
+    member(K-V, Pairs),
+    dict_field_key(K, Wanted),
+    Value = V.
+
+%% json_put/4: set a key path. Lists are read-only here — an index path is
+%% rejected, because building output is about setting fields, not splicing lists.
+json_put(Doc, Path, Value, Updated) :-
+    json_path_segments(Path, Segments),
+    Segments \== [],
+    \+ member(star, Segments),
+    % NB: `\+ ( member(S, Segments), integer(S) )`. Writing this as
+    % `\+ member(S, Segments), integer(S)` binds S inside the negation, so the
+    % whole guard fails for any non-empty path.
+    \+ ( member(Seg, Segments), integer(Seg) ),
+    json_put_walk(Doc, Segments, Value, Updated).
+
+json_put_walk(_Doc, [], Value, Value) :- !.
+json_put_walk(Doc, [Key|Rest], Value, Updated) :-
+    is_dict(Doc),
+    (   json_walk_1(Doc, Key, Old)
+    ->  json_put_walk(Old, Rest, Value, NewValue)
+    ;   json_put_walk(_{}, Rest, Value, NewValue)
+    ),
+    dict_field_key(Key, Key0),
+    put_dict(Key0, Doc, NewValue, Updated).
+
+%% json_text(+Dict, -Text): compact JSON. For layout or streaming use
+%% json_write_dict/3 from library(http/json).
+json_text(Dict, Text) :- atom_json_dict(Text, Dict, []).
+
+%% pattern(+Template, ?Text, ?Bindings)
+%%
+%% One syntax for building a string and for parsing it. Literal text matches
+%% exactly, and `$Name` marks a slot; the direction follows from what is bound:
+%%
+%%   pattern("Name: $Name, age: $Age", Text, [name="Ada", age=36])   % build
+%%   pattern("Name: $Name, age: $Age", "Name: Ada, age: 36", B)      % parse
+%%   pattern("DOI: $Doi:doi", Text, [doi=D])                         % typed slot
+%%
+%% `$` is the marker rather than `{…}` so a template can contain JSON or any other
+%% brace-bearing text verbatim, and so it never collides with the `{Var}`
+%% interpolation used in task/N descriptions. `$$` is a literal dollar.
+%%
+%% A template must be anchored by literal text: two slots separated only by nothing
+%% (`"$A$B"`) is rejected, rather than resolved arbitrarily. On parse a slot
+%% consumes up to the next literal, so the literals decide the split.
+pattern(Template, Text, Bindings) :-
+    pattern_tokens(Template, Tokens),
+    (   var(Text)
+    ->  pattern_build(Tokens, Bindings, Text)
+    ;   pattern_parse(Tokens, Text, Bindings)
+    ).
+
+%% pattern_tokens(+Template, -Tokens): [lit(CharList)|slot(NameChars, TypeChars)]
+pattern_tokens(Template, Tokens) :-
+    (   atom(Template) -> atom_string(Template, Text) ; Text = Template ),
+    string_chars(Text, Chars),
+    pattern_scan(Chars, [], Tokens),
+    pattern_check_anchored(Tokens).
+
+pattern_scan([], Acc, [lit(Text)]) :-
+    !,
+    reverse(Acc, Text).
+pattern_scan(['$', '$' | Rest], Acc, Tokens) :-
+    !,
+    pattern_scan(Rest, ['$' | Acc], Tokens).
+pattern_scan(['$' | Rest], Acc, Tokens) :-
+    !,
+    pattern_take_name(Rest, NameChars, Rest1),
+    NameChars \== [],
+    atom_chars(Name, NameChars),
+    (   Rest1 = [':' | Rest2],
+        pattern_take_name(Rest2, TypeChars, Rest3),
+        TypeChars \== []
+    ->  atom_chars(Type, TypeChars)
+    ;   Rest3 = Rest1, Type = none
+    ),
+    reverse(Acc, Text),
+    Tokens = [lit(Text), slot(Name, Type) | More],
+    pattern_scan(Rest3, [], More).
+pattern_scan([C | Rest], Acc, Tokens) :-
+    pattern_scan(Rest, [C | Acc], Tokens).
+
+%% A slot name is a run of characters that are not a template delimiter. Scanning by
+%% delimiter rather than by `char_type(C, alnum)` avoids depending on a ctypes
+%% predicate that is not guaranteed in this build.
+pattern_take_name([C | Rest], [C | More], Left) :-
+    \+ pattern_delimiter(C),
+    !,
+    pattern_take_name(Rest, More, Left).
+pattern_take_name(Rest, [], Rest).
+
+pattern_delimiter(' ').  pattern_delimiter('\t'). pattern_delimiter('\n').
+pattern_delimiter(':').  pattern_delimiter(',').  pattern_delimiter('.').
+pattern_delimiter(')').  pattern_delimiter(']').  pattern_delimiter('}').
+pattern_delimiter('$').  pattern_delimiter('-').  pattern_delimiter('/').
+pattern_delimiter('=').  pattern_delimiter('\'').
+
+%% Two slots with nothing between them cannot be told apart on parse.
+pattern_check_anchored(Tokens) :-
+    pattern_adjacent_slots(Tokens, A, B),
+    !,
+    format(atom(Msg),
+        'pattern: slots "~w" and "~w" are adjacent with no literal between them, so the split is ambiguous',
+        [A, B]),
+    throw(error(domain_error(pattern_unanchored, Msg), pattern_tokens/2)).
+pattern_check_anchored(_).
+
+pattern_adjacent_slots([slot(A, _), lit([]), slot(B, _) | _], A, B) :- !.
+pattern_adjacent_slots([_ | Rest], A, B) :- pattern_adjacent_slots(Rest, A, B).
+
+%% pattern_build(+Tokens, +Bindings, -Text)
+pattern_build(Tokens, Bindings, Text) :-
+    findall(Chars,
+        (   member(Token, Tokens),
+            pattern_build_token(Token, Bindings, Chars)
+        ),
+        Parts),
+    append(Parts, All),
+    string_chars(Text, All).
 
-%% Helper: resolve path relative to /workspace
-%% Prevents directory traversal outside workspace
-resolve_workspace_path(RelPath, FullPath) :-
-    (   atom(RelPath) -> atom_string(RelPath, RelPathStr)
-    ;   RelPathStr = RelPath
+pattern_build_token(lit(Chars), _, Chars) :- !.
+pattern_build_token(slot(Name, Type), Bindings, Chars) :-
+    (   member(Name=Value, Bindings)
+    ->  true
+    ;   member(Key=Value, Bindings), pattern_name(Key, Name)
+    ->  true
+    ;   format(atom(Msg), 'pattern: no value bound for slot "~w"', [Name]),
+        throw(error(uninstantiation_error(Msg), pattern/3))
     ),
-    % Remove leading slashes to make relative
-    (   sub_string(RelPathStr, 0, 1, _, "/")
-    ->  sub_string(RelPathStr, 1, _, 0, CleanPath)
-    ;   CleanPath = RelPathStr
+    pattern_render(Type, Value, Chars).
+
+pattern_render(none, Value, Chars) :- !, pattern_text_chars(Value, Chars).
+pattern_render(Type, Value, Chars) :-
+    (   memberchk(Type, [string, text])
+    ->  pattern_text_chars(Value, Chars)
+    ;   memberchk(Type, [int, integer, number])
+    ->  (   number(Value) -> format(string(S), "~w", [Value]) ; S = Value ),
+        string_chars(S, Chars)
+    ;   format(atom(Msg), 'pattern: unknown slot type "~w"', [Type]),
+        throw(error(domain_error(pattern_type, Msg), pattern/3))
+    ).
+
+%% Always a char LIST. Returning the string itself here silently corrupted the
+%% build: the parts list then held a string among char lists, and the final
+%% string_chars/2 failed on a mixed list.
+pattern_text_chars(Value, Chars) :-
+    (   string(Value) -> string_chars(Value, Chars)
+    ;   atom(Value) -> atom_chars(Value, Chars)
+    ;   number(Value) -> format(string(S), "~w", [Value]), string_chars(S, Chars)
+    ;   format(atom(Msg), 'pattern: cannot render ~w as text', [Value]),
+        throw(error(type_error(text, Msg), pattern/3))
+    ).
+
+%% pattern_parse(+Tokens, +Text, -Bindings)
+pattern_parse(Tokens, Text, Bindings) :-
+    % Always a char list: a string here would be one element and the literal
+    % matching below would never line up.
+    (   string(Text) -> string_chars(Text, Chars)
+    ;   atom(Text) -> atom_string(Text, S), string_chars(S, Chars)
+    ;   Chars = Text
     ),
-    % Prevent directory traversal
-    (   sub_string(CleanPath, _, _, _, "..")
-    ->  throw(error(permission_error(access, directory, RelPath), 
-                    context(resolve_workspace_path/2, 'Directory traversal not allowed')))
-    ;   true
+    is_list(Chars),
+    pattern_match(Tokens, Chars, Bindings).
+
+pattern_match([], [], []) :- !.
+pattern_match([lit(Lit)], Rest, []) :-
+    !,
+    append(Lit, [], Rest).
+pattern_match([lit(Lit), slot(Name, Type) | More], Chars, [Name=Value | Bindings]) :-
+    append(Lit, Rest0, Chars),
+    !,
+    (   More = [lit(Next) | _], Next \== []
+    ->  append(Taken, After, Rest0),
+        append(Next, _, After)
+    ;   Taken = Rest0,
+        After = []
     ),
-    % Build full path
-    atom_concat('/workspace/', CleanPath, FullPath).
+    pattern_capture(Type, Taken, Value),
+    pattern_match(More, After, Bindings).
+
+pattern_capture(none, Chars, Value) :- !, string_chars(Value, Chars).
+pattern_capture(Type, Chars, Value) :-
+    (   memberchk(Type, [string, text])
+    ->  string_chars(Value, Chars)
+    ;   memberchk(Type, [int, integer])
+    ->  (   catch(number_codes(N, Chars), _, fail), integer(N)
+        ->  Value = N
+        ;   format(atom(Msg), 'pattern: "~s" is not an integer', [Chars]),
+            throw(error(syntax_error(Msg), pattern/3))
+        )
+    ;   memberchk(Type, [number])
+    ->  (   catch(number_codes(N, Chars), _, fail)
+        ->  Value = N
+        ;   format(atom(Msg), 'pattern: "~s" is not a number', [Chars]),
+            throw(error(syntax_error(Msg), pattern/3))
+        )
+    ;   format(atom(Msg), 'pattern: unknown slot type "~w"', [Type]),
+        throw(error(domain_error(pattern_type, Msg), pattern/3))
+    ).
+
+%% pattern_name(+Key, +Name): compare a template slot name with a binding key the
+%% way dict_field does — atom or string, any case, separators ignored.
+pattern_name(Key, Name) :-
+    pattern_normalise(Key, A),
+    pattern_normalise(Name, B),
+    A == B.
+
+pattern_normalise(Value, Normalised) :-
+    (   atom(Value) -> atom_string(Value, Text) ; Text = Value ),
+    string_lower(Text, Lower),
+    split_string(Lower, " _-", "", Parts),
+    atomic_list_concat(Parts, '', Normalised).
+
+%% repl_inject_workspace_predicates(+SessionId)
+%% Idempotent: assertz/1 the same clauses twice is harmless (a duplicate clause
+%% yields the same solution once? no - it yields twice), so clear first.
+repl_inject_workspace_predicates(SessionId) :-
+    forall(( workspace_predicate_name(Name), between(0, 5, Arity) ),
+        catch(abolish(SessionId:Name/Arity), _, true)),
+    forall(workspace_predicate_clause(SessionId, Clause),
+        catch(assertz(Clause), _, true)).
+
+workspace_predicate_clause(S, (S:read_file(F, C) :-
+    system:read_file_to_string(F, C, []))).
+workspace_predicate_clause(S, (S:read_file_to_string(F, C, O) :-
+    system:read_file_to_string(F, C, O))).
+workspace_predicate_clause(S, (S:write_file(F, C) :-
+    system:open(F, write, St), system:write(St, C), system:close(St))).
+workspace_predicate_clause(S, (S:append_file(F, C) :-
+    system:open(F, append, St), system:write(St, C), system:close(St))).
+workspace_predicate_clause(S, (S:exists_file(F) :-
+    system:exists_file(F))).
+workspace_predicate_clause(S, (S:exists_directory(D) :-
+    system:exists_directory(D))).
+workspace_predicate_clause(S, (S:directory_files(D, L) :-
+    system:directory_files(D, L))).
+workspace_predicate_clause(S, (S:make_directory(D) :-
+    system:make_directory(D))).
+workspace_predicate_clause(S, (S:make_directory_path(D) :-
+    system:make_directory_path(D))).
+workspace_predicate_clause(S, (S:delete_file(F) :-
+    system:delete_file(F))).
+workspace_predicate_clause(S, (S:delete_directory(D) :-
+    system:delete_directory(D))).
+workspace_predicate_clause(S, (S:size_file(F, Sz) :-
+    system:size_file(F, Sz))).
+workspace_predicate_clause(S, (S:dict_field(D, K, V) :- deepclause_mi:dict_field(D, K, V))).
+workspace_predicate_clause(S, (S:dict_field(D, K, Def, V) :- deepclause_mi:dict_field(D, K, Def, V))).
+workspace_predicate_clause(S, (S:dict_field_key(K, N) :- deepclause_mi:dict_field_key(K, N))).
+workspace_predicate_clause(S, (S:json_get(D, P, V) :- deepclause_mi:json_get(D, P, V))).
+workspace_predicate_clause(S, (S:json_get(D, P, Def, V) :- deepclause_mi:json_get(D, P, Def, V))).
+workspace_predicate_clause(S, (S:json_gets(D, P, Vs) :- deepclause_mi:json_gets(D, P, Vs))).
+workspace_predicate_clause(S, (S:json_put(D, P, V, D2) :- deepclause_mi:json_put(D, P, V, D2))).
+workspace_predicate_clause(S, (S:json_text(D, T) :- deepclause_mi:json_text(D, T))).
+workspace_predicate_clause(S, (S:schema_fill(N, V, F) :-
+    deepclause_mi:schema_fields_of(S, N, Fields), deepclause_mi:schema_fill_fields(Fields, V, F))).
+workspace_predicate_clause(S, (S:pattern(T, Text, B) :- deepclause_mi:pattern(T, Text, B))).
+
+workspace_predicate_clause(S, (S:time_file(F, T) :-
+    system:time_file(F, T))).
+
+%% ============================================================
+%% File I/O - paths resolve against /workspace (see the note above)
+%% ============================================================
+
+%% File I/O paths
+%% `/workspace` is the host project, mounted by the WASM filesystem (NODEFS);
+%% its working directory is set to /workspace, so a relative path and a
+%% `/workspace/...` path name the same file. Every other absolute path is the
+%% ephemeral in-memory VM filesystem, not the host. There is no rewriting
+%% layer any more: the mount is the boundary.
 
 %% mi_call(consult(File), +StateIn, -StateOut)
 %% Load Prolog clauses from a file into the current session module
@@ -4314,8 +5197,7 @@ mi_call(consult(File), StateIn, StateIn) :-
     !,
     get_session_id(SessionId),
     guard_not_frozen(SessionId),
-    resolve_workspace_path(File, FullPath),
-    readutil:read_file_to_string(FullPath, Code, []),
+    system:read_file_to_string(File, Code, []),
     consult_string(Code, SessionId).
 
 mi_call(use_module(Module), StateIn, StateIn) :-
@@ -4413,22 +5295,19 @@ consult_process_term(Head, SessionId) :-
 %% mi_call(read_file_to_string(File, Content, Options), +StateIn, -StateOut)
 mi_call(read_file_to_string(File, Content, Options), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(File, FullPath),
-    readutil:read_file_to_string(FullPath, Content, Options).
+    system:read_file_to_string(File, Content, Options).
 
 %% mi_call(read_file(File, Content), +StateIn, -StateOut)
 %% Simplified version without options
 mi_call(read_file(File, Content), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(File, FullPath),
-    readutil:read_file_to_string(FullPath, Content, []).
+    system:read_file_to_string(File, Content, []).
 
 %% mi_call(write_file(File, Content), +StateIn, -StateOut)
 %% Write string content to a file
 mi_call(write_file(File, Content), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(File, FullPath),
-    open(FullPath, write, Stream),
+    open(File, write, Stream),
     write(Stream, Content),
     close(Stream).
 
@@ -4436,8 +5315,7 @@ mi_call(write_file(File, Content), StateIn, StateIn) :-
 %% Append string content to a file
 mi_call(append_file(File, Content), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(File, FullPath),
-    open(FullPath, append, Stream),
+    open(File, append, Stream),
     write(Stream, Content),
     close(Stream).
 
@@ -4445,19 +5323,13 @@ mi_call(append_file(File, Content), StateIn, StateIn) :-
 %% Open a file for reading/writing
 mi_call(open(File, Mode, Stream), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(File, FullPath),
-    open(FullPath, Mode, Stream).
+    open(File, Mode, Stream).
 
 %% mi_call(close(Stream), +StateIn, -StateOut)
 mi_call(close(Stream), StateIn, StateIn) :-
     !,
     close(Stream).
 
-%% mi_call(read_string(Stream, Length, Content), +StateIn, -StateOut)
-mi_call(read_string(Stream, Length, Content), StateIn, StateIn) :-
-    !,
-    read_string(Stream, Length, Content).
-
 %% mi_call(write(Stream, Content), +StateIn, -StateOut)
 mi_call(write(Stream, Content), StateIn, StateIn) :-
     !,
@@ -4466,60 +5338,51 @@ mi_call(write(Stream, Content), StateIn, StateIn) :-
 %% mi_call(exists_file(File), +StateIn, -StateOut)
 mi_call(exists_file(File), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(File, FullPath),
-    exists_file(FullPath).
+    exists_file(File).
 
 %% mi_call(exists_directory(Dir), +StateIn, -StateOut)
 mi_call(exists_directory(Dir), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(Dir, FullPath),
-    exists_directory(FullPath).
+    exists_directory(Dir).
 
 %% mi_call(directory_files(Dir, Files), +StateIn, -StateOut)
 mi_call(directory_files(Dir, Files), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(Dir, FullPath),
-    directory_files(FullPath, Files).
+    directory_files(Dir, Files).
 
 %% mi_call(make_directory(Dir), +StateIn, -StateOut)
 mi_call(make_directory(Dir), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(Dir, FullPath),
-    make_directory(FullPath).
+    make_directory(Dir).
 
 %% mi_call(make_directory_path(Dir), +StateIn, -StateOut)
 mi_call(make_directory_path(Dir), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(Dir, FullPath),
-    make_directory_path(FullPath).
+    make_directory_path(Dir).
 
 %% mi_call(delete_file(File), +StateIn, -StateOut)
 mi_call(delete_file(File), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(File, FullPath),
-    delete_file(FullPath).
+    delete_file(File).
 
 %% mi_call(delete_directory(Dir), +StateIn, -StateOut)
 mi_call(delete_directory(Dir), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(Dir, FullPath),
-    delete_directory(FullPath).
+    delete_directory(Dir).
 
 %% mi_call(size_file(File, Size), +StateIn, -StateOut)
 %% size_file/2 is a plain SWI builtin, so it would otherwise resolve `File`
 %% against the WASM process cwd (not the workspace) and demand `/workspace/...`.
 mi_call(size_file(File, Size), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(File, FullPath),
-    size_file(FullPath, Size).
+    size_file(File, Size).
 
 %% mi_call(time_file(File, Time), +StateIn, -StateOut)
 %% Modifications time (seconds since epoch); same workspace-relative rule as
 %% size_file/2.
 mi_call(time_file(File, Time), StateIn, StateIn) :-
     !,
-    resolve_workspace_path(File, FullPath),
-    time_file(FullPath, Time).
+    time_file(File, Time).
 
 %% ============================================================
 %% Catch/Throw - STATE THREADED
@@ -4625,6 +5488,7 @@ is_mi_special_predicate(prompt_named(_,_,_)). %% Transformed form of prompt/N
 is_mi_special_predicate(llm(_,_)).
 %% Tool scoping predicates
 is_mi_special_predicate(with_tools(_,_)).
+is_mi_special_predicate(with_fresh_memory(_)).
 is_mi_special_predicate(without_tools(_,_)).
 %% Reasoning effort scoping
 is_mi_special_predicate(with_reasoning(_,_)).
@@ -4856,6 +5720,14 @@ consume_gas(StateIn, StateOut) :-
 %% mi_call_dispatch(+Goal, +StateIn, -StateOut)
 %% Dispatch user-defined vs built-in predicates
 %% Uses separate clauses instead of if-then-else to preserve backtracking
+mi_call_dispatch(Goal, StateIn, StateIn) :-
+    get_session_id(SessionId),
+    callable(Goal),
+    predicate_property(SessionId:Goal, defined),
+    predicate_property(Goal, built_in),
+    !,
+    call(SessionId:Goal).
+
 mi_call_dispatch(Goal, StateIn, StateIn) :-
     predicate_property(Goal, built_in),
     !,  % Commit: it's built-in, no backtracking needed
@@ -4937,8 +5809,14 @@ var_to_name(Bindings, Var, Name) :-
 %% expand_interpolations(+Term, +Bindings, -ExpandedTerm)
 %% Walk a term and expand strings containing {VarName} patterns
 %% Bindings is a list of 'VarName'=Variable pairs from read_term
+%% Interpolation happens in goal position only: `task/N`/`prompt/N`/`output/1`/… and
+%% the arguments of a user goal, never inside a list, a dict, or another compound
+%% passed as data. See the note on expand_term_interp/3.
+expand_interpolations((Head :- Body), Bindings, (Head :- ExpandedBody)) :-
+    !,
+    expand_body_interp(Body, Bindings, ExpandedBody).
 expand_interpolations(Term, Bindings, ExpandedTerm) :-
-    expand_term_interp(Term, Bindings, ExpandedTerm).
+    expand_body_interp(Term, Bindings, ExpandedTerm).
 
 %% expand_term_interp(+Term, +Bindings, -Expanded)
 %% Main term expansion predicate
@@ -4947,13 +5825,16 @@ expand_interpolations(Term, Bindings, ExpandedTerm) :-
 expand_term_interp(Var, _, Var) :-
     var(Var), !.
 
-% Strings - check if they need interpolation
-expand_term_interp(String, Bindings, Expanded) :-
-    string(String), !,
-    (   string_needs_interpolation(String)
-    ->  build_format_goal(String, Bindings, Expanded)
-    ;   Expanded = String
-    ).
+% Strings are LITERAL here. Interpolation is decided by expand_body_interp/3, which
+% only rewrites a string that is a *direct argument of a goal*. Rewriting every
+% string, nested ones included, corrupted data: the shell command
+%   exec(bash(argv: [..., "-w", "%{http_code}", Url]), R)
+% had its `%{http_code}` element replaced by a format goal inside the argv list, so
+% the list arrived truncated at `-w`. A JSON document, a regex, an `awk` program and
+% a `jq` filter all contain braces and must survive verbatim.
+expand_term_interp(String, _, String) :-
+    string(String),
+    !.
 
 % Atoms - check if they need interpolation (for atom strings)
 expand_term_interp(Atom, Bindings, Expanded) :-
@@ -4999,6 +5880,19 @@ expand_term_interp(Term, Bindings, ExpandedTerm) :-
 expand_body_interp(Var, _, Var) :-
     var(Var), !.
 
+% A list or a dict is DATA, not a sequence of goals. Descending into one treats its
+% elements as goal arguments and hoists any `{...}` string it contains, which
+% rewrote data into a goal term:
+%   argv: ["curl","-w","%{http_code}","u"]   became
+%   argv: [curl,-w|((param(http_code,_),format(...)),[Temp,u])]
+% so `exec(bash(argv: [...]))` reached the shell with a truncated argument list.
+expand_body_interp(Data, _, Data) :-
+    (   Data == []
+    ;   Data = [_|_]
+    ;   is_dict(Data)
+    ),
+    !.
+
 % Conjunction
 expand_body_interp((A, B), Bindings, ExpandedConj) :- !,
     expand_body_interp(A, Bindings, EA),
@@ -5047,6 +5941,7 @@ expand_body_interp(Goal, Bindings, ExpandedGoal) :-
 expand_body_interp(Goal, Bindings, ExpandedGoal) :-
     compound(Goal),
     Goal =.. [Functor|Args],
+    interp_arg_predicate(Functor),
     expand_args_hoist(Args, Bindings, PreGoals, ExpandedArgs, true),
     !,
     Bare =.. [Functor|ExpandedArgs],
@@ -5062,6 +5957,21 @@ expand_body_interp(Goal, Bindings, ExpandedGoal) :-
 % Atoms/other
 expand_body_interp(Goal, _, Goal).
 
+%% Predicates whose string arguments interpolate `{Var}`. Interpolation lives in
+%% the *description* of an LLM step and in the question of a judgment; anywhere else
+%% a string is data and must survive verbatim. Hoisting for every goal made a string
+%% of data into a goal argument: `X = "%{code}"` became an interpolation of the
+%% variable `code`, and a shell argv containing `%{http_code}` was rewritten.
+%%
+%% (task/N, prompt/N, answer/1, system/1, user/1, output/1, log/1 and yield/1 are
+%% handled by goal_with_string_arg/4 above, for their first argument.)
+interp_arg_predicate(judge).
+interp_arg_predicate(choose).
+interp_arg_predicate(rate).
+interp_arg_predicate(verify).
+interp_arg_predicate(probability).
+interp_arg_predicate(holds).
+
 %% goal_with_string_arg(+Goal, -Functor, -StringArg, -RestArgs)
 %% Match goals that take a string as their first argument
 goal_with_string_arg(answer(S), answer, S, []) :- string(S).