accrete-kit 0.0.0-stage → 0.1.0

package/dist/scaffold/assets/contract/cli-v1.json

@@ -0,0 +1,296 @@
+{
+  "contract_id": "accrete-template-cli/v1",
+  "status": "Command catalog of the accrete Kernel this package carries, the version in accrete.cli of its package.json. Every entry and long flag is checked against that binary's --help by scripts/check-cli-contract.mjs.",
+  "architecture_edition": "2026-11-03",
+  "globals": [
+    "--project DIRECTORY",
+    "--state-dir DIRECTORY",
+    "--host LABEL",
+    "--json",
+    "--help",
+    "--version"
+  ],
+  "project_environment_variable": "ACCRETE_PROJECT",
+  "input": {
+    "from": "UTF-8 JSON, or Markdown for memory append",
+    "stdin": "--from - for object creation, amendments, Data locations and Memory; import and migrate need real paths",
+    "amendment": "JSON Merge Patch of editable fields",
+    "selector": "Object arguments accept a stable ID, a name or an alias; IDs take priority and an ambiguous alias is a conflict",
+    "id": "1-180 ASCII letters, digits, dots, underscores or hyphens, and not . or ..; generated as a UUID when not supplied"
+  },
+  "commands": [
+    {
+      "id": "project.migrate.legacy",
+      "command": "migrate",
+      "usage": "accrete migrate --from LEGACY [--dry-run]",
+      "effect": "Convert the old scaffold's metadata, retaining original backups and an identity map.",
+      "basis": "04 §6; 09"
+    },
+    {
+      "id": "project.migrate.format",
+      "command": "migrate",
+      "usage": "accrete migrate [--dry-run]",
+      "effect": "Handle persisted format changes, keeping identities and relationships. With only format 1 in existence it reports the project is current and changes nothing.",
+      "basis": "04 §6; 07 §6; 09"
+    },
+    {
+      "id": "config.resolve",
+      "command": "config resolve",
+      "usage": "accrete config resolve --json",
+      "effect": "Report resolved project roots, host, metadata view, state directory and index path without disclosing credentials or writing objects.",
+      "basis": "04 §7; 06 §2"
+    },
+    {
+      "id": "interface",
+      "command": "interface",
+      "usage": "accrete interface --json",
+      "effect": "Report CLI, interface and format versions and exit codes; needs no Workspace.",
+      "basis": "04 §8; 07 §10"
+    },
+    {
+      "id": "model.register",
+      "command": "model register",
+      "usage": "accrete model register [--from FILE] [--checkout PATH] [--id ID] [--name NAME] [--description TEXT] [--source-scope PATH]",
+      "effect": "Allocate a Model identity for an existing Git checkout or a repository locator supplied in JSON. Does not clone or fetch. A checkout becomes a host-local binding.",
+      "basis": "03 Model identity; 04 §7"
+    },
+    {
+      "id": "model.bind",
+      "command": "model bind",
+      "usage": "accrete model bind MODEL_ID --checkout PATH",
+      "effect": "Set this host's checkout binding for a known Model.",
+      "basis": "04 §7; 06 §2"
+    },
+    {
+      "id": "model.update",
+      "command": "model update",
+      "usage": "accrete model update MODEL_ID --from FILE --expect REVISION",
+      "effect": "Amend the Model descriptor; source history stays in Git.",
+      "basis": "04 §7"
+    },
+    {
+      "id": "model.retire",
+      "command": "model retire",
+      "usage": "accrete model retire MODEL_ID --expect REVISION [--from FILE]",
+      "effect": "End current use while preserving identity, repository and earlier associations. The optional JSON may carry reason.",
+      "basis": "03; 04 §7"
+    },
+    {
+      "id": "model.iteration.open",
+      "command": "model iteration open",
+      "usage": "accrete model iteration open MODEL_ID [--from FILE] [--id ID] [--name NAME] [--purpose TEXT] [--branch BRANCH] [--worktree PATH] [--start REVISION] [--existing]",
+      "effect": "Describe an iteration. --worktree creates a worktree of the Model's repository unless --existing attaches one; without --worktree no storage is allocated. Flags override --from fields of the same name.",
+      "basis": "03 Model identity; 04 §§5,7"
+    },
+    {
+      "id": "model.iteration.close",
+      "command": "model iteration close",
+      "usage": "accrete model iteration close ITERATION_ID --expect REVISION [--from FILE] [--outcome TEXT] [--commit COMMIT]",
+      "effect": "Retain the outcome, summary and every selected commit. Outcome is required from the file or --outcome; --commit repeats. Merging and worktree removal stay separate.",
+      "basis": "03 Model identity; 04 §§5,7"
+    },
+    {
+      "id": "model.iteration.remove-worktree",
+      "command": "model iteration remove-worktree",
+      "usage": "accrete model iteration remove-worktree ITERATION_ID [--force]",
+      "effect": "Remove the iteration's bound worktree through Git, keeping Git's refusal for changed work unless --force is given.",
+      "basis": "04 §§5,7"
+    },
+    {
+      "id": "tool.admit",
+      "command": "tool admit",
+      "usage": "accrete tool admit [--from FILE] [--id ID] [--name NAME] [--description TEXT] [--source PATH] [--source-mode live|retained] [--revision COMMIT]",
+      "effect": "Give an existing capability a Tool identity and explicit live or retained source selection.",
+      "basis": "04 §7; 08 §§7-8"
+    },
+    {
+      "id": "tool.bind",
+      "command": "tool bind",
+      "usage": "accrete tool bind TOOL_ID --source PATH",
+      "effect": "Set this host's source binding for a known Tool.",
+      "basis": "04 §7; 06 §2"
+    },
+    {
+      "id": "tool.update",
+      "command": "tool update",
+      "usage": "accrete tool update TOOL_ID --from FILE --expect REVISION",
+      "effect": "Amend metadata or source selection without changing the user's active implementation checkout.",
+      "basis": "04 §7; 08 §7"
+    },
+    {
+      "id": "tool.expose",
+      "command": "tool expose",
+      "usage": "accrete tool expose TOOL_ID --agent codex|claude [--mode wrapper|symlink] [--name NAME] [--destination DIRECTORY]",
+      "effect": "Create a project-local discovery binding to actual source material; default to a portable source-reading wrapper.",
+      "basis": "04 §7; 08 §§7-9"
+    },
+    {
+      "id": "tool.refresh",
+      "command": "tool refresh",
+      "usage": "accrete tool refresh TOOL_ID [--agent codex|claude]",
+      "effect": "Refresh existing managed exposures, reporting unavailable or pending source material; a retired Tool's local exposures are removed where possible.",
+      "basis": "04 §7; 08 §§7-9"
+    },
+    {
+      "id": "tool.retire",
+      "command": "tool retire",
+      "usage": "accrete tool retire TOOL_ID --expect REVISION [--from FILE]",
+      "effect": "Retain identity and associations while ending normal discovery; preserve source material and running work. The optional JSON may carry reason.",
+      "basis": "04 §7; 08 §7"
+    },
+    {
+      "id": "tool.export",
+      "command": "tool export",
+      "usage": "accrete tool export TOOL_ID --to PATH",
+      "effect": "Create a new local directory with tool.json and source/; external publication remains a separate action.",
+      "basis": "04 §7; 08 §7"
+    },
+    {
+      "id": "data.register",
+      "command": "data register",
+      "usage": "accrete data register --from FILE [--id ID] [--name NAME] [--description TEXT] [--result RESULT_ID] [--live]",
+      "effect": "Describe Data and usable locations without mandatory payload copying, packing or hashing.",
+      "basis": "04 §7; 06 §§3-5"
+    },
+    {
+      "id": "data.register.path",
+      "command": "data register",
+      "usage": "accrete data register --path PATH [--id ID] [--name NAME] [--description TEXT] [--kind file|directory|collection|external] [--hash] [--result RESULT_ID] [--live]",
+      "effect": "Register a local borrowed path in place. --hash computes SHA-256 for one regular file.",
+      "basis": "06 §4"
+    },
+    {
+      "id": "data.amend",
+      "command": "data amend",
+      "usage": "accrete data amend DATA_ID --from FILE --expect REVISION",
+      "effect": "Change descriptive metadata. Closed content and the locations array cannot change this way.",
+      "basis": "03; 06 §3"
+    },
+    {
+      "id": "data.location.add",
+      "command": "data location add",
+      "usage": "accrete data location add DATA_ID [--from FILE] [--location NAME] [--path PATH] [--kind filesystem|rclone|external] [--expect REVISION]",
+      "effect": "Add a borrowed locator for the same described content; do not redefine earlier Result inputs. A repeated matching location is a no-op.",
+      "basis": "04 §7; 06 §4"
+    },
+    {
+      "id": "data.materialize",
+      "command": "data materialize",
+      "usage": "accrete data materialize DATA_ID [--to LOCATION] [--source SOURCE_LOCATION] [--expect REVISION]",
+      "effect": "Produce and publish a managed replica at a configured filesystem location (default working) using local transfer or the configured rclone adapter.",
+      "basis": "04 §7; 06 §6"
+    },
+    {
+      "id": "data.evict",
+      "command": "data evict",
+      "usage": "accrete data evict DATA_ID --location LOCATION [--expect REVISION]",
+      "effect": "Remove precisely one Kernel-managed replica named by location ID or name, preserving the Data identity and other locations. An ambiguous name is a conflict.",
+      "basis": "04 §7; 06 §7"
+    },
+    {
+      "id": "data.retire",
+      "command": "data retire",
+      "usage": "accrete data retire DATA_ID --expect REVISION [--from FILE]",
+      "effect": "End current use while preserving identity, locations and earlier associations; no bytes are removed. The optional JSON may carry reason.",
+      "basis": "03; 06 §7"
+    },
+    {
+      "id": "result.record",
+      "command": "result record",
+      "usage": "accrete result record [--from FILE] [--id ID] [--name NAME] [--description TEXT] [--observe-checkout PATH]",
+      "effect": "Persist a useful activity description and its supplied Model, Tool and Data associations. --observe-checkout adds a separately labelled recording-time observation.",
+      "basis": "04 §4"
+    },
+    {
+      "id": "result.amend",
+      "command": "result amend",
+      "usage": "accrete result amend RESULT_ID --from FILE --expect REVISION",
+      "effect": "Apply an explicit correction or enrichment against the actual current document bytes.",
+      "basis": "04 §4; 05 §2"
+    },
+    {
+      "id": "result.observe",
+      "command": "result observe",
+      "usage": "accrete result observe RESULT_ID --text-file FILE [--operation-id ID]",
+      "effect": "Append an independent observation to the observations array; an operation ID makes retries unambiguous.",
+      "basis": "04 §4; 05 §2"
+    },
+    {
+      "id": "result.capture",
+      "command": "result capture",
+      "usage": "accrete result capture --checkout PATH --path SOURCE_PATH --to DIRECTORY",
+      "effect": "Write a selected binary Git diff and selected nonignored untracked files to a new directory with a manifest of the captured scope. --path repeats. It is not a complete executable environment.",
+      "basis": "04 §§4-5"
+    },
+    {
+      "id": "memory.append",
+      "command": "memory append",
+      "usage": "accrete memory append --from FILE [--id ID] [--title TITLE] [--authored-at RFC3339] [--result ID] [--model ID] [--tool ID] [--data ID] [--supersedes ID] [--links-from FILE]",
+      "effect": "Publish complete authored Markdown with a stable ID, timezone-based path and repeatable object links. Retry a lost acknowledgement with the same --id.",
+      "basis": "04 §4; 05 §5"
+    },
+    {
+      "id": "index.refresh",
+      "command": "index refresh",
+      "usage": "accrete index refresh",
+      "effect": "Refresh the host-local disposable SQLite projection from the selected metadata view.",
+      "basis": "04 §4; 05 §3"
+    },
+    {
+      "id": "export",
+      "command": "export",
+      "usage": "accrete export --to PATH [--id ID]",
+      "effect": "Write a metadata bundle of selected or all managed documents. Payloads, Git objects, Tool source and machine bindings stay out. --id repeats.",
+      "basis": "05; 06 §9"
+    },
+    {
+      "id": "import",
+      "command": "import",
+      "usage": "accrete import --from PATH [--allow-foreign]",
+      "effect": "Import a metadata bundle object by object, reporting each outcome. A batch is not atomic; repeating it completes missing entries.",
+      "basis": "05; 06 §9"
+    },
+    {
+      "id": "recover",
+      "command": "recover",
+      "usage": "accrete recover [--operation OPERATION_ID]",
+      "effect": "Reconcile interrupted transfers, evictions, worktree creation and uncertain publications from their receipts. Never relaunches scientific computation. --operation limits Data reconciliation to one operation.",
+      "basis": "04 §§5,8; 06 §6"
+    }
+  ],
+  "receipt": {
+    "success_required": [
+      "object_id",
+      "path",
+      "revision",
+      "committed",
+      "index_pending"
+    ],
+    "success_optional": [
+      "published",
+      "durability",
+      "unchanged"
+    ],
+    "multi_effects": "enumerate actual written paths and any pending projections/exposures",
+    "index_pending": "primary publication succeeded; exit 0; repair with index refresh",
+    "published_uncertain": "published=true, durability=uncertain, object ID/path and recovery details; exit 8; continue with recover",
+    "error": "stable category plus committed/published state and surviving paths",
+    "exit_codes": {
+      "0": "success, including a committed document whose index refresh is pending",
+      "2": "invalid invocation, input or unsupported format",
+      "3": "unresolved configuration or project, or absent object",
+      "4": "revision, identity, ownership or destination conflict",
+      "5": "native dependency unavailable",
+      "6": "storage failure before the requested publication completes",
+      "7": "incomplete external operation or partially failed import",
+      "8": "publication is visible but durability is uncertain"
+    }
+  },
+  "excluded": [
+    "general query/list/show wrappers",
+    "mandatory run wrapper",
+    "agent scheduler",
+    "automatic public Tool publication",
+    "persistent-operation Skill scripts"
+  ]
+}

package/dist/scaffold/assets/contract/example-inputs.json

@@ -0,0 +1,38 @@
+[
+  {
+    "file": ".accrete/examples/model-register.json",
+    "definition": "modelRegister"
+  },
+  {
+    "file": ".accrete/examples/iteration-open.json",
+    "definition": "iterationOpen"
+  },
+  {
+    "file": ".accrete/examples/iteration-close.json",
+    "definition": "iterationClose"
+  },
+  {
+    "file": ".accrete/examples/tool-admit.json",
+    "definition": "toolAdmit"
+  },
+  {
+    "file": ".accrete/examples/tool-update.json",
+    "definition": "toolUpdate"
+  },
+  {
+    "file": ".accrete/examples/tool-retire.json",
+    "definition": "retire"
+  },
+  {
+    "file": ".accrete/examples/data-register.json",
+    "definition": "dataRegister"
+  },
+  {
+    "file": ".accrete/examples/result-record.json",
+    "definition": "resultRecord"
+  },
+  {
+    "file": ".accrete/examples/result-amend.json",
+    "definition": "resultAmend"
+  }
+]