{ "classes": { "Contract": { "abstract": true, "description": "A constraint on the reachable effects of a program." }, "EffectCall": { "abstract": true, "description": "An individual trusted call event." }, "FilesystemAppendFile": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.append_file", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "path": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The path argument to tools.filesystem.trusted.effects.append_file.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.append_file.path" }, "text": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The text argument to tools.filesystem.trusted.effects.append_file.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.append_file.text" } }, "class_uri": "cz:tools.filesystem.trusted.effects.append_file", "description": "Append ``text`` to the UTF-8 contents of ``path``.\n\nCreates parent directories and the file as needed.", "is_a": "EffectCall" }, "FilesystemChmod": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.chmod", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "mode": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The mode argument to tools.filesystem.trusted.effects.chmod.", "range": "integer", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.chmod.mode" }, "path": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The path argument to tools.filesystem.trusted.effects.chmod.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.chmod.path" } }, "class_uri": "cz:tools.filesystem.trusted.effects.chmod", "description": "Set the permission bits of ``path`` to ``mode``.", "is_a": "EffectCall" }, "FilesystemCopy": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.copy", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "dest": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The dest argument to tools.filesystem.trusted.effects.copy.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.copy.dest" }, "src": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The src argument to tools.filesystem.trusted.effects.copy.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.copy.src" } }, "class_uri": "cz:tools.filesystem.trusted.effects.copy", "description": "Copy ``src`` to ``dest`` (file or directory tree).", "is_a": "EffectCall" }, "FilesystemCreatesAtMost": { "annotations": { "cnl_template": "Filesystem tools create at most {count} directories or empty files.", "python_symbol": "tools.filesystem.trusted.contracts.creates_at_most", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "count": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The count argument to tools.filesystem.trusted.contracts.creates_at_most.", "range": "integer", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.creates_at_most.count" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.creates_at_most", "description": "Guarantee at most ``count`` directories or empty files are created.", "is_a": "Contract" }, "FilesystemDeletesAtMost": { "annotations": { "cnl_template": "Filesystem tools delete or move away at most {count} paths.", "python_symbol": "tools.filesystem.trusted.contracts.deletes_at_most", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "count": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The count argument to tools.filesystem.trusted.contracts.deletes_at_most.", "range": "integer", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.deletes_at_most.count" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.deletes_at_most", "description": "Guarantee at most ``count`` removals (a move counts as one).", "is_a": "Contract" }, "FilesystemFind": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.find", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "args": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The args argument to tools.filesystem.trusted.effects.find.", "multivalued": true, "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.find.args" }, "path": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The path argument to tools.filesystem.trusted.effects.find.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.find.path" } }, "class_uri": "cz:tools.filesystem.trusted.effects.find", "description": "List paths using -name, -path, -type f/d/l, -mindepth, and -maxdepth.\n\nFilters are combined with AND. -not may negate a name/path/type filter.\nInvalid arguments raise ValueError before starting a subprocess. Traversal\nuses -P for encountered symlinks; root-path resolution can still follow\nsymlinks, including roots ending in \"/\" or \"/.\". Output is NUL-delimited.\nContracts constrain the lexical starting path, not resolved confinement.", "is_a": "EffectCall" }, "FilesystemGrep": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.grep", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "path": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The path argument to tools.filesystem.trusted.effects.grep.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.grep.path" }, "pattern": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The pattern argument to tools.filesystem.trusted.effects.grep.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.grep.pattern" } }, "class_uri": "cz:tools.filesystem.trusted.effects.grep", "description": "Return the lines in ``path`` that contain the substring ``pattern``.", "is_a": "EffectCall" }, "FilesystemListsAtMost": { "annotations": { "cnl_template": "Filesystem tools list directories at most {count} times.", "python_symbol": "tools.filesystem.trusted.contracts.lists_at_most", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "count": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The count argument to tools.filesystem.trusted.contracts.lists_at_most.", "range": "integer", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.lists_at_most.count" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.lists_at_most", "description": "Guarantee at most ``count`` ``find`` walks occur.", "is_a": "Contract" }, "FilesystemMakeDir": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.make_dir", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "path": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The path argument to tools.filesystem.trusted.effects.make_dir.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.make_dir.path" } }, "class_uri": "cz:tools.filesystem.trusted.effects.make_dir", "description": "Create directory ``path`` (with parents).", "is_a": "EffectCall" }, "FilesystemMove": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.move", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "dest": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The dest argument to tools.filesystem.trusted.effects.move.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.move.dest" }, "src": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The src argument to tools.filesystem.trusted.effects.move.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.move.src" } }, "class_uri": "cz:tools.filesystem.trusted.effects.move", "description": "Move ``src`` to ``dest``.\n\nA move is read as reading and deleting its source and writing its\ndestination, so a file cannot be moved out from under a read policy and\nread under its new name.", "is_a": "EffectCall" }, "FilesystemMustNotWrite": { "annotations": { "cnl_template": "No text a filesystem tool writes to a file contains {substring}.", "python_symbol": "tools.filesystem.trusted.contracts.must_not_write", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "substring": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The substring argument to tools.filesystem.trusted.contracts.must_not_write.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.must_not_write.substring" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.must_not_write", "description": "Guarantee no written or appended text contains ``substring``.\n\nA secrets / banned-content guard before content reaches disk. Copies and\nmoves write existing contents, not text, so they are not covered.", "is_a": "Contract" }, "FilesystemNeverDeleteUnder": { "annotations": { "cnl_template": "No filesystem tool deletes or moves a path starting with {prefix}, or a directory containing it (paths compared as written).", "python_symbol": "tools.filesystem.trusted.contracts.never_delete_under", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "prefix": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The prefix argument to tools.filesystem.trusted.contracts.never_delete_under.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.never_delete_under.prefix" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.never_delete_under", "description": "Guarantee nothing under ``prefix`` is removed or moved.\n\nThe blast-radius guard for handing an agent ``rm``: e.g.\n``never_delete_under(\"/home/user/.ssh\")``.", "is_a": "Contract" }, "FilesystemNeverListUnder": { "annotations": { "cnl_template": "No filesystem tool lists a directory starting with {prefix}, or one containing it (paths compared as written).", "python_symbol": "tools.filesystem.trusted.contracts.never_list_under", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "prefix": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The prefix argument to tools.filesystem.trusted.contracts.never_list_under.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.never_list_under.prefix" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.never_list_under", "description": "Guarantee no ``find`` walk starts at, under, or above ``prefix``.\n\nThe listing counterpart of ``never_read_under``, which covers contents\nonly. Walking a directory that contains ``prefix`` reveals its names, so\nthat is refused too. This is what ``find.never_read_under`` used to say.", "is_a": "Contract" }, "FilesystemNeverReadUnder": { "annotations": { "cnl_template": "No filesystem tool reads, copies or moves a path starting with {prefix}, or a directory containing it (paths compared as written).", "python_symbol": "tools.filesystem.trusted.contracts.never_read_under", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "prefix": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The prefix argument to tools.filesystem.trusted.contracts.never_read_under.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.never_read_under.prefix" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.never_read_under", "description": "Guarantee no file contents under ``prefix`` reach the program or a copy.\n\nListing a directory that contains ``prefix`` is allowed: it reveals the\nname, not the contents. Use ``only_read_under`` to confine listings too.", "is_a": "Contract" }, "FilesystemNeverWriteUnder": { "annotations": { "cnl_template": "No filesystem tool modifies a path starting with {prefix}, or a directory containing it (paths compared as written).", "python_symbol": "tools.filesystem.trusted.contracts.never_write_under", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "prefix": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The prefix argument to tools.filesystem.trusted.contracts.never_write_under.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.never_write_under.prefix" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.never_write_under", "description": "Guarantee no modification, of any kind, touches ``prefix``.", "is_a": "Contract" }, "FilesystemNoChmods": { "annotations": { "cnl_template": "No filesystem tool changes permission bits.", "python_symbol": "tools.filesystem.trusted.contracts.no_chmods", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": {}, "class_uri": "cz:tools.filesystem.trusted.contracts.no_chmods", "description": "Guarantee the program changes no permission bits.", "is_a": "Contract" }, "FilesystemNoCreates": { "annotations": { "cnl_template": "No filesystem tool creates a directory or empty file.", "python_symbol": "tools.filesystem.trusted.contracts.no_creates", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": {}, "class_uri": "cz:tools.filesystem.trusted.contracts.no_creates", "description": "Guarantee no ``make_dir`` or ``touch`` occurs.", "is_a": "Contract" }, "FilesystemNoDeletes": { "annotations": { "cnl_template": "No filesystem tool deletes or moves anything away.", "python_symbol": "tools.filesystem.trusted.contracts.no_deletes", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": {}, "class_uri": "cz:tools.filesystem.trusted.contracts.no_deletes", "description": "Guarantee nothing is removed, including by moving it.\n\nOverwriting a file is a write, not a delete; see ``never_write_under``.", "is_a": "Contract" }, "FilesystemNoGuarantees": { "annotations": { "cnl_template": "No restrictions are imposed on filesystem effects.", "python_symbol": "tools.filesystem.trusted.contracts.no_guarantees", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": {}, "class_uri": "cz:tools.filesystem.trusted.contracts.no_guarantees", "description": "Make no guarantees about filesystem effects.", "is_a": "Contract" }, "FilesystemNoReads": { "annotations": { "cnl_template": "No filesystem tool reads a file or lists a directory.", "python_symbol": "tools.filesystem.trusted.contracts.no_reads", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": {}, "class_uri": "cz:tools.filesystem.trusted.contracts.no_reads", "description": "Guarantee the program neither reads files nor lists directories.", "is_a": "Contract" }, "FilesystemOnlyDeleteUnder": { "annotations": { "cnl_template": "Everything a filesystem tool deletes or moves away starts with {root}.", "python_symbol": "tools.filesystem.trusted.contracts.only_delete_under", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "root": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The root argument to tools.filesystem.trusted.contracts.only_delete_under.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.only_delete_under.root" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.only_delete_under", "description": "Guarantee every removed (or moved) path is under ``root``.", "is_a": "Contract" }, "FilesystemOnlyModes": { "annotations": { "cnl_template": "Every filesystem chmod sets a mode in {allowlist}, written in decimal.", "python_symbol": "tools.filesystem.trusted.contracts.only_modes", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "allowlist": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The allowlist argument to tools.filesystem.trusted.contracts.only_modes.", "multivalued": true, "range": "integer", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.only_modes.allowlist" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.only_modes", "description": "Guarantee every chmod sets a mode in ``allowlist``.\n\nBitwise masking is not expressible in a contract lambda, so permission\nsafety is stated as an explicit allowlist of whole modes, e.g.\n``only_modes([0o644, 0o755, 0o600, 0o700])`` \u2014 which by construction admits\nno world-writable, setuid, or setgid bits.", "is_a": "Contract" }, "FilesystemOnlyPattern": { "annotations": { "cnl_template": "Every grep search uses exactly the pattern {pattern}.", "python_symbol": "tools.filesystem.trusted.contracts.only_pattern", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "pattern": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The pattern argument to tools.filesystem.trusted.contracts.only_pattern.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.only_pattern.pattern" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.only_pattern", "description": "Guarantee every ``grep`` search uses exactly this pattern.", "is_a": "Contract" }, "FilesystemOnlyReadUnder": { "annotations": { "cnl_template": "Every file a filesystem tool reads or lists starts with {root}.", "python_symbol": "tools.filesystem.trusted.contracts.only_read_under", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "root": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The root argument to tools.filesystem.trusted.contracts.only_read_under.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.only_read_under.root" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.only_read_under", "description": "Legacy literal-prefix policy, including suffixes such as README.md.bak.\n\nPrefer only_reads_files for exact names or only_reads_files_under for a\ndirectory boundary. This helper retains its original prefix semantics.", "is_a": "Contract" }, "FilesystemOnlyReadsFiles": { "annotations": { "cnl_template": "Filesystem tools read only the exact files {files}; directory listings and copy or move sources are forbidden.", "python_symbol": "tools.filesystem.trusted.contracts.only_reads_files", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "files": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The files argument to tools.filesystem.trusted.contracts.only_reads_files.", "multivalued": true, "range": "FilePath", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.only_reads_files.files" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.only_reads_files", "description": "Allow reads of these exact files (one or many), never a name prefix.\n\nBare and leading ./ spellings are equivalent. An empty list permits no\nreads or listings. Copy and move may recursively read directories, so this\ncontract refuses them even when their source looks like a file name.\nPaths are lexical: no existence, symlink or hard-link checks are implied.", "is_a": "Contract" }, "FilesystemOnlyReadsFilesUnder": { "annotations": { "cnl_template": "Filesystem tools read or list only paths in the directory {directory} or its subdirectories (paths compared lexically).", "python_symbol": "tools.filesystem.trusted.contracts.only_reads_files_under", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "directory": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The directory argument to tools.filesystem.trusted.contracts.only_reads_files_under.", "range": "DirectoryPath", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.only_reads_files_under.directory" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.only_reads_files_under", "description": "Confine reads, listings, and copy/move sources to a directory boundary.\n\nDirectoryPath(\"data\") permits data and data/a.txt, but not database/a.txt.\nA trailing slash is optional; ./data and data are equivalent. DirectoryPath\n(\".\") permits relative paths only; DirectoryPath(\"/\") permits absolute\npaths only. Paths are lexical, without existence or symlink checks.", "is_a": "Contract" }, "FilesystemOnlyWriteUnder": { "annotations": { "cnl_template": "Every modification by a filesystem tool is to a path starting with {root}.", "python_symbol": "tools.filesystem.trusted.contracts.only_write_under", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "root": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The root argument to tools.filesystem.trusted.contracts.only_write_under.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.only_write_under.root" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.only_write_under", "description": "Legacy literal-prefix policy, including suffixes such as test.md.bak.\n\nPrefer only_writes_files for exact files or only_writes_files_under for\na directory boundary. This helper retains its original prefix semantics.\nA move deletes its source, so moving a file out of ``root`` is refused too.", "is_a": "Contract" }, "FilesystemOnlyWritesFiles": { "annotations": { "cnl_template": "Filesystem tools modify only the exact paths {files}; copy, move, remove and explicit directory creation are forbidden. Parent directories may be created when writing or touching a file.", "python_symbol": "tools.filesystem.trusted.contracts.only_writes_files", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "files": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The files argument to tools.filesystem.trusted.contracts.only_writes_files.", "multivalued": true, "range": "FilePath", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.only_writes_files.files" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.only_writes_files", "description": "Confine modifications to exact file names (one or many), never prefixes.\n\nAllows write_file, append_file, touch and chmod at the listed paths.\nCopy, move and remove may modify whole directories, so they are refused;\nmake_dir is refused too. An empty list permits no modifications. Parent\ndirectories implicitly created by write_file, append_file or touch are\nallowed and are not separate write events. Bare and leading ./ spellings\nare equivalent. Paths are lexical: existence, file type and symlink or\nhard-link targets are not checked. Reads are not restricted by this contract.", "is_a": "Contract" }, "FilesystemOnlyWritesFilesUnder": { "annotations": { "cnl_template": "Filesystem tools modify only paths in the directory {directory} or its subdirectories (paths compared lexically). Implicit creation of parent directories is allowed.", "python_symbol": "tools.filesystem.trusted.contracts.only_writes_files_under", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "directory": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The directory argument to tools.filesystem.trusted.contracts.only_writes_files_under.", "range": "DirectoryPath", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.only_writes_files_under.directory" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.only_writes_files_under", "description": "Confine all modification paths to a directory boundary, including deletes.\n\nCovers write, append, touch, make_dir, chmod, copy destinations, and both\nthe source and destination of moves. Reads are unrestricted. DirectoryPath\n(\"data\") permits data/a but not database/a. Bare and ./ paths are equivalent;\na trailing slash is optional. Dot permits relative paths, slash absolute\npaths. Implicit parent-directory creation may reach above the boundary.\nPaths are lexical, without existence, symlink or hard-link checks.", "is_a": "Contract" }, "FilesystemReadFile": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.read_file", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "path": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The path argument to tools.filesystem.trusted.effects.read_file.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.read_file.path" } }, "class_uri": "cz:tools.filesystem.trusted.effects.read_file", "description": "Read and return the UTF-8 text contents of ``path``.", "is_a": "EffectCall" }, "FilesystemReadLine": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.read_line", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "line_number": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The line_number argument to tools.filesystem.trusted.effects.read_line.", "range": "integer", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.read_line.line_number" }, "path": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The path argument to tools.filesystem.trusted.effects.read_line.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.read_line.path" } }, "class_uri": "cz:tools.filesystem.trusted.effects.read_line", "description": "Read a one-based line, without its terminator; return empty at EOF.\n\nDecode UTF-8 with universal newline handling. Preserve all other whitespace.", "is_a": "EffectCall" }, "FilesystemReadLines": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.read_lines", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "path": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The path argument to tools.filesystem.trusted.effects.read_lines.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.read_lines.path" } }, "class_uri": "cz:tools.filesystem.trusted.effects.read_lines", "description": "Read UTF-8 logical lines without terminators, using str.splitlines.\n\nEmpty files return []; blank lines are retained; a final unterminated\nline counts. This is not wc -l, which counts LF bytes. Decode and I/O\nerrors propagate, as with read_file.", "is_a": "EffectCall" }, "FilesystemReadOnly": { "annotations": { "cnl_template": "No filesystem tool modifies anything. Effects of other libraries, such as git or rsync, are not covered.", "python_symbol": "tools.filesystem.trusted.contracts.read_only", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": {}, "class_uri": "cz:tools.filesystem.trusted.contracts.read_only", "description": "Guarantee no write, append, create, delete, move, copy or chmod occurs.", "is_a": "Contract" }, "FilesystemReadsAtMost": { "annotations": { "cnl_template": "Filesystem tools read files at most {count} times.", "python_symbol": "tools.filesystem.trusted.contracts.reads_at_most", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "count": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The count argument to tools.filesystem.trusted.contracts.reads_at_most.", "range": "integer", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.reads_at_most.count" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.reads_at_most", "description": "Guarantee at most ``count`` reads (a copy or move reads its source).", "is_a": "Contract" }, "FilesystemRemove": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.remove", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "path": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The path argument to tools.filesystem.trusted.effects.remove.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.remove.path" } }, "class_uri": "cz:tools.filesystem.trusted.effects.remove", "description": "Delete ``path`` \u2014 a file, or a directory and everything under it.", "is_a": "EffectCall" }, "FilesystemTouch": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.touch", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "path": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The path argument to tools.filesystem.trusted.effects.touch.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.touch.path" } }, "class_uri": "cz:tools.filesystem.trusted.effects.touch", "description": "Create empty file ``path`` (or bump its mtime).", "is_a": "EffectCall" }, "FilesystemWriteFile": { "annotations": { "python_symbol": "tools.filesystem.trusted.effects.write_file", "source_sha256": "c638b09f8ca5aafcd918d41e471d0af0ee43bf5a5eea0e1e14e90cc5d3451d36" }, "attributes": { "content": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The content argument to tools.filesystem.trusted.effects.write_file.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.write_file.content" }, "path": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The path argument to tools.filesystem.trusted.effects.write_file.", "range": "string", "required": true, "slot_uri": "cz:tools.filesystem.trusted.effects.write_file.path" } }, "class_uri": "cz:tools.filesystem.trusted.effects.write_file", "description": "Write ``content`` to ``path`` as UTF-8 text, creating parent dirs.", "is_a": "EffectCall" }, "FilesystemWriteLengthAtMost": { "annotations": { "cnl_template": "Text a filesystem tool writes to a file is at most {max_chars} characters.", "python_symbol": "tools.filesystem.trusted.contracts.write_length_at_most", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "max_chars": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The max_chars argument to tools.filesystem.trusted.contracts.write_length_at_most.", "range": "integer", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.write_length_at_most.max_chars" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.write_length_at_most", "description": "Guarantee every written or appended text is at most ``max_chars`` long.", "is_a": "Contract" }, "FilesystemWritesAtMost": { "annotations": { "cnl_template": "Filesystem tools make at most {count} modifications.", "python_symbol": "tools.filesystem.trusted.contracts.writes_at_most", "renderer_version": 1, "source_sha256": "e223fa2c48c656f9b7262093a72aec96ca08eea3a356f1b4f876de156bfce91c" }, "attributes": { "count": { "annotations": { "python_parameter_kind": "POSITIONAL_OR_KEYWORD" }, "description": "The count argument to tools.filesystem.trusted.contracts.writes_at_most.", "range": "integer", "required": true, "slot_uri": "cz:tools.filesystem.trusted.contracts.writes_at_most.count" } }, "class_uri": "cz:tools.filesystem.trusted.contracts.writes_at_most", "description": "Guarantee at most ``count`` modifications (a move counts twice).", "is_a": "Contract" } }, "default_prefix": "cz", "default_range": "string", "description": "Generated from trusted Python definitions. Classes describe contract invocations and effect calls; exports do not establish program safety.", "id": "https://normalform-ai.github.io/clauz3/schema/contracts/v1", "imports": [ "linkml:types" ], "name": "clauz3_contracts", "prefixes": { "cz": "https://normalform-ai.github.io/clauz3/schema/contracts/v1/", "linkml": "https://w3id.org/linkml/" }, "title": "clauz3 filesystem contract catalog", "types": { "DirectoryPath": { "description": "A lexical directory boundary.", "typeof": "string" }, "FilePath": { "description": "An exact lexical file path.", "typeof": "string" } }, "version": "1" }