toolgraph 0.3.0__tar.gz → 0.4.0__tar.gz

{toolgraph-0.3.0 → toolgraph-0.4.0}/CHANGELOG.md

@@ -2,6 +2,353 @@
 
 All notable changes to Toolgraph are documented here.
 
+## 0.4.0 - 2026-10-21
+
+Fifth alpha. Read **Upgrading from 0.3.0** below before installing: it lists
+eight changes an existing setup, script or embedding program can notice.
+Most setups need no change, because the new refusals reject only identities
+and notes that hold credential-shaped data. What most often notices is
+tooling that reads Toolgraph's text: evidence paths, error lines and log
+output are shown differently, and more often withheld whole.
+
+### Upgrading from 0.3.0
+
+- A governance manifest or `servers.yaml` holding a credential-shaped
+  identity is refused at input (#217): an agent, policy id, tool ref or
+  `granted_by`, a `governed_by` policy or tool-ref key, or a server's name.
+  The manifest is rejected whole, so `ingest-manifest`, `policy propose` and
+  `policy impact` exit 1, and so is a `servers.yaml`, before any server is
+  contacted. A crawled server that reports such a tool name, or such a name
+  when `servers.yaml` gives it none, fails its own crawl; the rest of the
+  fleet still loads. The error names the field, never the value. Rename the
+  identity. A graph keeps the values it stored earlier until they are
+  re-ingested or reset.
+- Identities refuse any URI with an `@` after its `://`, raw or as `%40`
+  (#210, #215, #216), where 0.3.0 refused only a `user:password@` it could
+  bound: agent ids, tool keys, run ids, candidates and graph instance ids in
+  preflight, policy bundles, review plans, `policy impact` and `policy
+  propose`, the run ids and tool keys of a Tracegraph review report, and a
+  control plan's identities and keys. `policy propose` refuses to emit a
+  proposal whose note would list a live-graph tool key holding userinfo.
+- Review notes, reviewer names and control plans refuse a URI with a quote
+  in its userinfo and an `@` after it (#210), such as
+  `neo4j://u:"p w"@host`, which 0.3.0 accepted. A quoted URL followed by an
+  address in the same text, `"https://h" mail a@b`, is refused too.
+- Artifact evidence shows resource URIs differently (#212). A consumer that
+  matches evidence text should expect `https://<redacted-uri>` when an `@`
+  follows a URI's authority (`https://registry/@scope/pkg`), and
+  `<redacted-uri>` for a percent-encoded scheme. A resource that cannot be
+  parsed is now hidden instead of stopping the command, `export:///sink`
+  keeps its three slashes, and the paths of `check-access`, `unsafe-tools`,
+  `blast-radius`, `audit-report` and the matching MCP tools show resources
+  and policy ids redacted. The raw `resource` and `policy` row values are
+  unchanged. See the first bullets under Changed.
+- Diagnostics read differently, and more of them are withheld whole (#206,
+  #221, #223, #229, #232, #236). Validation errors are one line with fixed
+  text and `<key>` for keys outside the schema; YAML errors read `invalid
+  YAML at line L, column C: <what failed>`; MCP tool-call errors for a bad
+  request no longer quote it; a CLI usage error is withheld whole when a
+  token on the command line, or the tokens joined by spaces, is
+  credential-shaped; and a printed path that is
+  credential-shaped reads `<path withheld: credential-shaped>`. Messages
+  holding an escaped credential, or a URL whose path ends in a credential
+  name with text after it, are withheld: `Error accessing
+  https://host/token: connection refused` now reads `details withheld (they
+  contain credential-shaped data)`. Tooling
+  that matches stderr or MCP error text should expect these forms; the
+  entries under Fixed give each one.
+- Logging changes for programs that embed Toolgraph (#206). Importing
+  `toolgraph.server.app` into a process with no root log handler filters
+  the root handlers the MCP SDK then creates, and running the Typer app
+  in-process filters `logging.lastResort` for the rest of the process once a
+  command reaches the root callback (root `--help`, `--version` and an
+  unknown command do not). Every record through a
+  filtered handler, the program's own included, is rebuilt: its message is
+  scrubbed (`password=<redacted>`), each exception in its chain is shown as
+  `<Type>: <message>` without a traceback, and `extra` attributes and `stack_info` are dropped,
+  so a formatter that names an `extra` field fails with `Formatting field
+  not found in record`. Configure logging before importing
+  `toolgraph.server.app`, or replace the handlers it filtered. Handlers a
+  program configured itself are not touched.
+- Library callers: `ingest_governance`, `dry_run_ingest` and
+  `load_crawl_result` re-validate the model they are given, and a model
+  built with `model_construct()` or changed after validation that no longer
+  validates raises `ValueError: <Model> does not validate; build it with
+  <Model>.model_validate to see why` before the graph is opened.
+  `build_policy_impact` already re-validated, and now raises that error
+  instead of pydantic's. A YAML failure that PyYAML does not mark with a line
+  and column raises `toolgraph.yaml_loader.YAMLContentError`, a `ValueError`
+  (#223); marked failures still raise PyYAML's `MarkedYAMLError`.
+- A durability warning escalated with `-W error` ends a command with one
+  `ERROR:` line and exit 1, without a traceback or a JSON receipt (#129).
+  `init` keeps the database it created, where 0.3.0 deleted it and kept the
+  `config.json` naming it. The annotation warning's text now ends `do not
+  retry: a retry appends a second event`.
+
+### Changed
+
+- Artifact evidence shows each resource URI as a whole value (#212). A
+  resource is redacted before it is written into an evidence path, and
+  resource fields (`resource`, `resource_uri`, `read_resource`,
+  `write_resource`, `policy`, a resource `ref` and the `resources_*` lists of
+  `ingest-manifest --dry-run --json`) are redacted as one value even when
+  they hold whitespace. In free text, such as an exception reason, a URI ends
+  at whitespace or at a `)`, as in 0.3.0. Consumers that match evidence can
+  notice:
+  - An `@` anywhere after a URI's authority, raw or as `%40`, hides
+    everything after the scheme, since where an unquoted password ends cannot
+    be told: `https://registry/@scope/pkg` is shown as
+    `https://<redacted-uri>`. In free text the rest of the text goes too, as
+    it already did after a quoted password, because it may hold the rest of
+    the password; this includes a URI-shaped tool name inside evidence text.
+  - A value whose scheme is percent-encoded (`https%3A%2F%2Fh/r`) is shown as
+    `<redacted-uri>`, in free text with the rest of the text.
+  - A resource value that cannot be parsed (`https://u:p@[::1/r`) is hidden
+    as `<scheme>://<redacted-uri>` instead of stopping the command, and so is
+    any evidence string that is nothing but such a URI, whitespace around it
+    aside. A URI that cannot be parsed among other text, such as
+    `see https://u:p@[::1/r` in an exception reason, still stops it, as in
+    0.3.0.
+  - An evidence path no longer loses the rest of its line when its resource
+    holds a `)` or a quoted password: a resource `neo4j://u:p)ss@host/r` is
+    shown as `(t) -READS-> (neo4j://host/r) -GOVERNED_BY-> (p:DENY)`, and a
+    quoted one as `(t) -READS-> (neo4j://<redacted-uri>) -GOVERNED_BY->
+    (p:DENY)`. In free text, a `)` followed by an `@` hides everything after
+    the scheme.
+  - `export:///sink` keeps its three slashes; it was shown as `export:/sink`.
+- Paths in `check-access`, `unsafe-tools`, `blast-radius` and `audit-report`
+  output, and in the matching MCP tools, show resources and policy ids the
+  same way. The rows still carry the raw `resource` and `policy` values
+  beside the path.
+- `ingest-manifest` warnings that name a resource show it redacted.
+- Identities are refused when they hold a URI with an `@` anywhere after its
+  `://`, raw or percent-encoded (#210): agent ids, tool keys, run ids,
+  candidates and graph instance ids in preflight, policy bundle, review plan,
+  policy impact and `policy propose` input and output, and the run ids and
+  tool keys of a Tracegraph review report. Before, only a `user:password@`
+  that the refusal rule could bound was refused, so `neo4j://u:p/w@host/r`
+  passed. An identity has no reason to hold userinfo, and an unquoted
+  password may hold `/`, `)` or whitespace. Review notes, reviewer names,
+  the notes of `policy propose` rows and control plans keep the rule for
+  prose. The live-graph tool keys an ambiguous grant's note lists are
+  checked as identities before they are joined into it, so `policy propose`
+  refuses to emit a proposal whose note would show one holding userinfo
+  (#216).
+
+- The governance manifest and the crawler refuse a credential-shaped identity
+  at input, with the same identity rule (#217): an agent, policy id, tool ref
+  or `granted_by`, a `governed_by` policy or tool-ref key, a server's name
+  (its `servers.yaml` name, else the name it reports) and the tool names it
+  reports. Before, such a
+  value was stored and printed by `check-access`, `unsafe-tools`,
+  `blast-radius`, `unbacked-edges`, `audit-report` and `eligible-tools`. The
+  error names the field, never the value. A manifest is rejected whole
+  (`ingest-manifest`, `policy propose` and `policy impact` exit 1), and so
+  is a `servers.yaml`, before any server is contacted. A server without a
+  `servers.yaml` name that reports such a name, or any server that reports
+  such a tool name, fails its own crawl, and the rest of the fleet still
+  loads; a server's own reported name is never stored when `servers.yaml`
+  names it. Resource URIs are not identities and are not checked. A graph
+  keeps the values it stored earlier until they are re-ingested or reset.
+
+- A control plan's identities get the identity rule at load (#215): `run_id`,
+  producer name and version, principal ids, node ids and the principals a
+  node lists, edge endpoints and candidate tools, so a credential URI with a
+  `/` in its password or a percent-encoded scheme is refused there instead of
+  being published as the result's `run_id`. Keys are field names and get the
+  same rule, so a duplicate or forbidden-field error can no longer print an
+  encoded credential-shaped key. String values of additive fields keep the
+  prose rule. The result's `graph_state` goes through the same artifact
+  check as the rest of the result.
+
+### Fixed
+
+- Artifact evidence no longer shows URI passwords the evidence scan could not
+  bound (#212). Before, a password holding an unquoted `/`, `?` or `#`
+  (`neo4j://u:p/w@host/r`, also read as a port when it starts with digits),
+  a credential URI inside another URI's path, an encoded `@` (`%40`), and a
+  resource whose query holds `)` (`https://h/r?k=a)b` kept `)b`) could reach
+  preflight, policy bundle, control-plan and review artifacts, `policy
+  impact` and `policy check` output and `ingest-manifest --dry-run --json`,
+  including its warnings. Inside free text some shapes are still not
+  bounded, as in 0.3.0: a password holding whitespace without quotes, a
+  query or fragment holding `)` (`see https://h/r?k=a)b` still shows `)b`),
+  and text after a `)` that no longer reads as a URI.
+- A URI with a quote in its userinfo and an `@` after it is refused like any
+  other credential URI, raw or percent-encoded (#210): in identities, review
+  notes, reviewer names and control plans. Before, a quoted password holding
+  whitespace (`neo4j://u:"p w"@host`), a quoted part after a `?` or `#`
+  (`neo4j://u:p?"w s"@host`, `neo4j://u?x:"p w"@host`) and a quoted user
+  part (`neo4j://"u v":"p w"@host`) were accepted. The refusal now matches
+  what error-message scrubbing already hides, so a quoted URL followed by an
+  address in the same text (`"https://h" mail a@b`, `"https://h:443" mail
+  a@b`) is refused too; `see "https://x/y" and @alice`, whose quote follows
+  a path, is not. Error messages hide the new shapes as well: before,
+  `neo4j://u:p?"w s"@h/a` kept `"w s"@h/a`. A message whose decoded or
+  scrubbed text still holds such a URI is withheld, as one holding
+  `u:%22pw%22@` already was; `see "https://x/y" and @alice` as an error
+  message is now withheld for that reason. Userinfo whose unquoted part
+  holds whitespace (`neo4j://u v:"p w"@host`) still passes in prose and in
+  error messages, where it reads as a URL followed by text; identities
+  refuse it.
+- Pydantic validation errors no longer print mapping keys, unknown field
+  names or input values (#221). Before, an invalid `servers.yaml` or
+  governance manifest (`crawl`, `ingest-manifest`, `policy impact`,
+  `policy propose`), an invalid review-candidate sidecar, and a server whose
+  `tools/list` reply the MCP SDK rejects printed the error location with
+  every key on the way, and the SDK's errors also printed the input; only the
+  credential shapes the scrubber recognizes were hidden, so
+  `governed_by: {"postgres://u:prefix QXZQ@h/x": ...}` showed `QXZQ@h/x` and
+  an `env` key showed as written. These errors are now one line, such as
+  `1 validation error for ServersConfig: servers.0.env.<key>: expected a
+  string [type=string_type]`: field names, list indexes and union member
+  names that match the schema are kept, any other key is `<key>`, and the
+  message is fixed text chosen by error type. A field's own refusal, such as
+  `agent must not contain credential-shaped data`, is kept as written.
+  Where Toolgraph cannot tell which model failed (`policy propose`, a
+  rejected server reply) no location is printed.
+- A config file that is not valid YAML is reported as `invalid YAML at line L,
+  column C: <what failed>`, such as `could not be parsed` or `duplicate key`
+  (#223). Before, the message quoted the source line, and names from the
+  document: a duplicate key, an alias, anchor or tag, a character. A value
+  PyYAML could not convert was reported with the value (`!!int x`,
+  `!!float x`, `!!bool x`), or stopped `policy impact` and `policy propose`
+  with a traceback (`!!bool x`, `!!timestamp x`, an empty `!!int`); now it is
+  `invalid YAML: a value could not be read`. Invalid UTF-8 and a control
+  character name only their position.
+  Library callers still get PyYAML's error when it marks a line and column
+  (a `MarkedYAMLError`); the other failures raise
+  `toolgraph.yaml_loader.YAMLContentError`, a `ValueError`.
+- Log output hides credential-shaped values and no longer prints tracebacks
+  (#206). Before, a crawled server whose reply failed JSON-RPC validation
+  made `crawl` print the MCP SDK's traceback with the reply's values
+  (`input_value=...`), a tool that crashed under `serve` logged its
+  exception message and traceback, and the SDK logged an unknown tool name
+  as sent. Now the CLI's fallback output (Python's last-resort handler, used
+  when no handler is configured) and the handlers the server configures
+  when the process has none print each record's message through the
+  credential scrubber, and each exception in its chain as
+  `<Type>: <message>` without its traceback, scrubbed the same way, with a validation error's
+  message rebuilt as in #221. A value the message or an exception prints
+  with `repr` (`%r`, a `KeyError` key), which escapes a tab or a no-break
+  space out of the scrubber's sight, is checked as it was before formatting,
+  and a credential-shaped one withholds the line. Other text in a message,
+  such as a tool name that is not credential-shaped, is still shown. Handlers a program
+  configured itself, before or after importing Toolgraph, and uvicorn's own
+  loggers under `serve --http` (#226), are not filtered.
+- MCP tool-call errors for a bad request no longer quote the request (#206).
+  Before, the MCP SDK answered an unknown tool with `Unknown tool: <name>` as
+  sent, and invalid arguments with pydantic's text, which carried every
+  input value (`input_value={'token': ...}`). The tool name now goes through
+  the credential scrubber (`Unknown tool: nope` is unchanged), and invalid
+  arguments read `Error executing tool <name>: 1 validation error for
+  <name>Arguments: agent: expected a string [type=string_type]`, with field
+  names and fixed messages as in #221. A tool that crashes keeps the SDK's
+  generic `Error executing tool <name>`. Errors for resources and prompts,
+  which Toolgraph does not register, and the HTTP transport's reply to a
+  malformed JSON-RPC body still come from the SDK as they are.
+- CLI usage errors and printed paths no longer show credential-shaped input
+  (#206). Before, Click's and Typer's own usage errors quoted what was typed
+  (`No such command '<arg>'`, `'<value>' is not a valid float`), as did
+  Toolgraph's (`unknown profile '<value>'`), and lines such as
+  `Invalid servers config at <path>` and the `--config` error printed the
+  path as given. A usage error is now withheld whole when a token on the
+  command line is credential-shaped, or the tokens joined by spaces are
+  (`password =hunter2` typed as two arguments), checked as typed, before
+  Click or Typer quotes or escapes them (`\x09`, `\xa0`) in the message;
+  otherwise its
+  message goes through the credential scrubber. Lines in
+  which Toolgraph prints a path it was given or created (`init`, `check`,
+  `crawl`, `ingest-manifest`, `example init`, `policy propose --output`, and
+  the runtime-config errors) show a credential-shaped path as
+  `<path withheld: credential-shaped>` and keep the rest of the line, and
+  an error from the operating system prints its file names the same way
+  (`[Errno 2] No such file or directory: '<path>'`) instead of quoting them
+  with `repr`, which escaped a tab out of the scrubber's sight. A typo reads
+  as before (`No such command 'chek'. Did you mean 'check'?`); a value the
+  scrubber treats as an assignment, such as `token:v2`, is still masked
+  (`'token=<redacted>`). The `"output"` path in the JSON receipts of `policy compile`,
+  `policy review-plan`, `policy impact --output`, `preflight` and
+  `control-preflight` is left as given: it names the file the caller asked
+  for.
+- Diagnostics that print a value with `repr` no longer show a credential
+  whose tab or no-break space it escaped (#229). Before, `repr`, `ascii`,
+  `%r`, a list or dict printed whole, a `KeyError` key and library errors
+  such as `invalid literal for int() with base 10: '<value>'` or
+  `could not convert string to float: b'<value>'` printed
+  `password<TAB>=secret` as `password\t=secret`, which the scrubber does not
+  read as an assignment: in `unknown profile` errors from the MCP tools, the
+  `AGENT_NOT_FOUND` line of the selector commands, `policy propose`
+  observation errors, and log records whose arguments were bytes or
+  containers. Now every message that goes through the credential scrubber
+  (CLI errors, MCP error text, log records, printed paths) is read as given
+  for str and bytes literals that hold a backslash escape, exactly as `repr`
+  or `ascii` prints them; such a literal that reads back as
+  credential-shaped, alone or in place in the message, withholds the whole
+  message, and so do more than 32 such literals. A literal without an
+  escape is scrubbed as before (`'password=secret'` reads
+  `'password=<redacted>`). Ordinary text is unchanged: a path is read only
+  when quoted as `repr` would quote it, so `C:\bearer\notes.json` is still
+  shown. A message that holds an escaped literal and also a credential the
+  scrubber would mask is withheld instead of masked. Not read: a literal
+  printed through `repr` twice, one right after an odd run of backslashes,
+  and one cut without its closing quote, as `int()` prints a value whose
+  repr is longer than 200 characters; the `int()` error itself is now
+  rendered without its value (#236, below). Artifact and evidence text,
+  which is stored rather than printed, is not affected.
+- An `int()` error and a reply the MCP SDK could not parse no longer show
+  a credential from the value they quote (#236, #239). Both print a
+  shortened repr the scrubber cannot read back: `int()` cuts it at 200
+  characters with no closing quote, and the SDK copies pydantic's error, which
+  shortens `input_value` in the middle and can split an escape such as
+  `\x01` or drop the quote that decided repr's quote character. A
+  streamable-http server answering a crawl with a JSON string showed
+  `password<TAB>=secret` in the `[error]` line, and an `int()` error
+  chained under a withheld one showed it in a log record. Now a
+  `ValueError` whose only argument is `int()`'s text prints
+  `invalid literal for int() with base N (value not shown)`, and an MCP
+  error with the JSON-RPC parse error code (-32700), including one a server
+  sent itself, prints `the server's reply could not be parsed (JSON-RPC
+  parse error)`, wherever Toolgraph renders an exception: crawl failures,
+  log records (where an exception whose arguments are credential-shaped is
+  still withheld whole, as before) and every exception `doctor` reports,
+  which now renders exceptions like the other commands. Not covered: an
+  `int()` error raised as a `ValueError` subclass (a `str` subclass whose
+  `__repr__` raises one), and `re.Match` reprs (`%.50R`).
+- A credential name at the end of a URL no longer leaves its value readable
+  in a scrubbed message (#232). The scrubber rewrites each URL to its origin
+  before it masks credentials, and a URL ends at whitespace or a quote, so
+  `fetch http://h/password =secret` printed `fetch http://h =secret`; so did
+  a name in a query (`?token =x`), with a tab or `: ` after it,
+  `.../authorization: Basic x`, `.../bearer x`, and a bracketed value
+  starting in the URL (`.../token=[a, x]`). Such a message is now withheld
+  whole. The text cannot tell a prose colon from an assignment, so
+  diagnostics whose URL path ends in a credential name with text after it
+  are withheld too: `Error accessing https://host/token: connection
+  refused`, `GET https://h/oauth/bearer returned 404`, `Client error for url
+  'https://h/token='`, `GET https://h/password={id} returned 404`, a host
+  that is a credential name (`Error accessing https://token: connection
+  refused`), and a name in the host position of a malformed scheme
+  (`1https://password : x`, which was masked). A value that starts inside
+  the URL and continues past a quote, `<`, `>` or a tab
+  (`http://h/x?token=abc"def` shows `"def`, and with an input placeholder
+  `http://h/token=abc<redacted>x` shows `http://h>x`), is not caught, nor
+  are forms only the scrubber reads as an assignment: `.../password :x`,
+  `.../password:[a, x]`, `.../authorization=Basic x` and
+  `.../proxy_authorization=Basic x` (#241).
+- A command that writes a file or a review annotation no longer prints a
+  traceback when the durability warning is escalated to an error (#129).
+  The warning (`ArtifactDurabilityWarning`, or
+  `ReviewCandidateDurabilityWarning` for `review-candidates annotate`) is
+  raised after the write is published, when the directory could not be
+  fsynced. With `-W error` the command still fails, as asked, but with one
+  `ERROR:` line and exit 1 instead of a traceback; no JSON receipt is
+  printed. Before, `init` also deleted the database it had just created
+  while keeping the published `config.json` that names it; both are now
+  kept. The annotation warning now ends `do not retry: a retry appends a
+  second event`, since the event is already recorded. Library calls still
+  raise the escalated warning after publication.
+
 ## 0.3.0 - 2026-10-19
 
 Fourth alpha. Read **Upgrading from 0.2.0** below before installing: it lists

{toolgraph-0.3.0 → toolgraph-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toolgraph
-Version: 0.3.0
+Version: 0.4.0
 Summary: Graph-native MCP/tool registry, policy compiler, and impact analyzer
 Project-URL: Homepage, https://github.com/memtomem/toolgraph
 Project-URL: Documentation, https://github.com/memtomem/toolgraph/blob/main/docs/beginner-guide.md
@@ -342,8 +342,13 @@ come from the orchestrator and Tracegraph runs against your own fleet.
 `preflight` wraps the same deterministic selector rules and stamps the result
 with a bracketed `graph_generation`. It remains advisory: rejected candidates
 produce `decision: advisory_warn` and exit 0. Unknown agents produce
-`unresolved_identity`, never a false allow. Resource URIs in evidence are
-scrubbed of userinfo and query strings before the artifact is written. Pass
+`unresolved_identity`, never a false allow. Resource URIs in evidence paths
+and resource fields are scrubbed of userinfo, query strings and fragments
+before the artifact is written; one with an `@` after its authority, or one
+that cannot be parsed, is shown as `<scheme>://<redacted-uri>`. Inside free
+text, such as an exception reason, a URI ends at whitespace or `)`, so a
+query or fragment holding `)` (`https://h/r?k=a)b`) still shows what follows
+the `)`. Pass
 `--features` only when the consumer needs the full selector feature rows.
 With `--out` the artifact is written privately and atomically, and the command
 prints a result envelope carrying `artifact_digest` — the SHA-256 of the exact
@@ -378,11 +383,14 @@ Local review notes may cite paths but reject credential-shaped content: a
 `<name>=`, or a `<name>:` followed by a space or a quote, where the name is a
 token, password, secret, credential, API key or authorization, so `token:
 rotated weekly` has to be rephrased while a versioned tool name such as
-`srv::get_token:v2` is fine. Reviewer names and the report's run ids and tool
-keys are checked the same way.
+`srv::get_token:v2` is fine. Reviewer names are checked the same way, and the
+report's run ids and tool keys more strictly: as identities, they also refuse
+any URI with an `@` after its `://`.
 If a genuine parent-directory fsync error occurs after replacement, the event
 remains successful and visible while a durability warning is written to stderr;
-retrying would append a duplicate event.
+retrying would append a duplicate event. With that warning escalated to an
+error (`-W error`), `annotate` exits 1 with one `ERROR:` line, and the event is
+still recorded: do not retry.
 
 Candidate ids use the same exact-tuple UUIDv5 as SyncMill's merged
 `board import-review-candidates` consumer (SyncMill PR #57), so the two human
@@ -472,12 +480,20 @@ to stderr) and exit 0 by default — gating is opt-in.
 | `audit-report --fail-on-blocking` | 1 when `status` is `fail` (unsafe violations or drifted governed tools) |
 | `preflight` | 0 for advisory allow, warn, and unresolved identity · 1 when the artifact cannot be built or written |
 | `control-preflight` | 0 including advisory warnings · 1 on an invalid plan or an I/O failure |
-| `policy compile` | 0 after atomic bundle replacement · 1 on unresolved identity/state or I/O failure |
+| `policy compile` | 0 after atomic bundle replacement (see the note below on escalated durability warnings) · 1 on unresolved identity/state or I/O failure |
 | `policy review-plan` | 0 · 1 on an invalid or stale report, unresolved graph state, or I/O failure |
 | `policy propose` | 0 · 1 on invalid input or a refused export · 2 for `--json` with `--output`, or `--min-would-block` below 1 |
 | `review-candidates list/annotate` | 0 on valid JSON output · 1 on invalid/stale artifacts or I/O failure · 2 on invalid CLI arguments |
 | `example init` | 2 when the destination already exists |
 
+A command that writes a file (`init`, `preflight --out`, `control-preflight
+--out`, `policy impact --output`, `policy compile`, `policy review-plan`,
+`policy propose --output`) or a review annotation warns on stderr and exits as
+above when the file is published but its directory could not be fsynced. With
+that warning escalated to an error (`-W error`), it exits 1 with one `ERROR:`
+line and prints no receipt; the file or event is published, but its crash
+durability is uncertain.
+
 An error outside these classes exits 1 with a Python traceback instead of an
 `ERROR:` line.
 

{toolgraph-0.3.0 → toolgraph-0.4.0}/README.md

@@ -303,8 +303,13 @@ come from the orchestrator and Tracegraph runs against your own fleet.
 `preflight` wraps the same deterministic selector rules and stamps the result
 with a bracketed `graph_generation`. It remains advisory: rejected candidates
 produce `decision: advisory_warn` and exit 0. Unknown agents produce
-`unresolved_identity`, never a false allow. Resource URIs in evidence are
-scrubbed of userinfo and query strings before the artifact is written. Pass
+`unresolved_identity`, never a false allow. Resource URIs in evidence paths
+and resource fields are scrubbed of userinfo, query strings and fragments
+before the artifact is written; one with an `@` after its authority, or one
+that cannot be parsed, is shown as `<scheme>://<redacted-uri>`. Inside free
+text, such as an exception reason, a URI ends at whitespace or `)`, so a
+query or fragment holding `)` (`https://h/r?k=a)b`) still shows what follows
+the `)`. Pass
 `--features` only when the consumer needs the full selector feature rows.
 With `--out` the artifact is written privately and atomically, and the command
 prints a result envelope carrying `artifact_digest` — the SHA-256 of the exact
@@ -339,11 +344,14 @@ Local review notes may cite paths but reject credential-shaped content: a
 `<name>=`, or a `<name>:` followed by a space or a quote, where the name is a
 token, password, secret, credential, API key or authorization, so `token:
 rotated weekly` has to be rephrased while a versioned tool name such as
-`srv::get_token:v2` is fine. Reviewer names and the report's run ids and tool
-keys are checked the same way.
+`srv::get_token:v2` is fine. Reviewer names are checked the same way, and the
+report's run ids and tool keys more strictly: as identities, they also refuse
+any URI with an `@` after its `://`.
 If a genuine parent-directory fsync error occurs after replacement, the event
 remains successful and visible while a durability warning is written to stderr;
-retrying would append a duplicate event.
+retrying would append a duplicate event. With that warning escalated to an
+error (`-W error`), `annotate` exits 1 with one `ERROR:` line, and the event is
+still recorded: do not retry.
 
 Candidate ids use the same exact-tuple UUIDv5 as SyncMill's merged
 `board import-review-candidates` consumer (SyncMill PR #57), so the two human
@@ -433,12 +441,20 @@ to stderr) and exit 0 by default — gating is opt-in.
 | `audit-report --fail-on-blocking` | 1 when `status` is `fail` (unsafe violations or drifted governed tools) |
 | `preflight` | 0 for advisory allow, warn, and unresolved identity · 1 when the artifact cannot be built or written |
 | `control-preflight` | 0 including advisory warnings · 1 on an invalid plan or an I/O failure |
-| `policy compile` | 0 after atomic bundle replacement · 1 on unresolved identity/state or I/O failure |
+| `policy compile` | 0 after atomic bundle replacement (see the note below on escalated durability warnings) · 1 on unresolved identity/state or I/O failure |
 | `policy review-plan` | 0 · 1 on an invalid or stale report, unresolved graph state, or I/O failure |
 | `policy propose` | 0 · 1 on invalid input or a refused export · 2 for `--json` with `--output`, or `--min-would-block` below 1 |
 | `review-candidates list/annotate` | 0 on valid JSON output · 1 on invalid/stale artifacts or I/O failure · 2 on invalid CLI arguments |
 | `example init` | 2 when the destination already exists |
 
+A command that writes a file (`init`, `preflight --out`, `control-preflight
+--out`, `policy impact --output`, `policy compile`, `policy review-plan`,
+`policy propose --output`) or a review annotation warns on stderr and exits as
+above when the file is published but its directory could not be fsynced. With
+that warning escalated to an error (`-W error`), it exits 1 with one `ERROR:`
+line and prints no receipt; the file or event is published, but its crash
+durability is uncertain.
+
 An error outside these classes exits 1 with a Python traceback instead of an
 `ERROR:` line.
 

{toolgraph-0.3.0 → toolgraph-0.4.0}/toolgraph/__init__.py

@@ -1,3 +1,3 @@
 """toolgraph — graph-native MCP/tool registry for advisory governance analysis."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"