operator.json

{
  "schema_version": "operator.v0",
  "name": "lock",
  "version": "0.3.2",
  "description": "Dataset lockfile tool: pins artifacts, fingerprints, and tool versions into a self-hashed immutable JSON artifact",
  "repository": "https://github.com/cmdrvl/lock",
  "license": "MIT",
  "agent_guide": "https://github.com/cmdrvl/.github/blob/main/profile/AGENT_PROMPT.md",

  "invocation": {
    "binary": "lock",
    "usage": [
      "lock [<input>] [OPTIONS]",
      "lock verify <LOCKFILE> [--root <DIR>] [--json] [--no-witness] [--strict]",
      "lock witness <query|last|count> [OPTIONS]"
    ],
    "output_mode": "artifact",
    "output_schema": "lock.v0",
    "json_flag": null
  },

  "arguments": [
    {
      "name": "input",
      "type": "file_path",
      "required": false,
      "position": 0,
      "description": "Versioned JSONL manifest file from upstream tools (default: stdin)"
    }
  ],

  "options": [
    {
      "name": "dataset_id",
      "flag": "--dataset-id",
      "type": "string",
      "description": "Logical dataset identifier"
    },
    {
      "name": "as_of",
      "flag": "--as-of",
      "type": "string",
      "description": "Point-in-time annotation (ISO 8601)"
    },
    {
      "name": "note",
      "flag": "--note",
      "type": "string",
      "description": "Free-text annotation"
    },
    {
      "name": "output",
      "flag": "--output",
      "type": "file_path",
      "description": "Write lockfile to this path instead of stdout (avoids self-inclusion when path is inside vacuum root)"
    },
    {
      "name": "no_witness",
      "flag": "--no-witness",
      "type": "flag",
      "description": "Suppress witness ledger recording for this run"
    },
    {
      "name": "describe",
      "flag": "--describe",
      "type": "flag",
      "description": "Print compiled operator.json and exit 0"
    },
    {
      "name": "schema",
      "flag": "--schema",
      "type": "flag",
      "description": "Print lock.v0 JSON Schema and exit 0"
    },
    {
      "name": "version",
      "flag": "--version",
      "type": "flag",
      "description": "Print lock <semver> and exit 0"
    }
  ],

  "subcommands": [
    {
      "name": "witness",
      "description": "Witness ledger query commands",
      "status": "available",
      "actions": [
        {
          "name": "query",
          "usage": "lock witness query [--tool <name>] [--since <iso8601>] [--until <iso8601>] [--outcome <LOCK_CREATED|LOCK_PARTIAL|REFUSAL>] [--input-hash <substring>] [--limit <n>] [--json]"
        },
        {
          "name": "last",
          "usage": "lock witness last [--json]"
        },
        {
          "name": "count",
          "usage": "lock witness count [--tool <name>] [--since <iso8601>] [--until <iso8601>] [--outcome <LOCK_CREATED|LOCK_PARTIAL|REFUSAL>] [--input-hash <substring>] [--json]"
        }
      ],
      "current_runtime_behavior": {
        "success_exit_code": 0,
        "no_match_exit_code": 1,
        "error_exit_code": 2,
        "ledger_path_resolution": [
          "EPISTEMIC_WITNESS",
          "~/.epistemic/witness.jsonl"
        ]
      }
    },
    {
      "name": "verify",
      "description": "Verify lockfile integrity and optionally member content",
      "status": "available",
      "usage": "lock verify <LOCKFILE> [--root <DIR>] [--json] [--no-witness] [--strict]",
      "arguments": [
        {
          "name": "lockfile",
          "type": "file_path",
          "required": true,
          "position": 0,
          "description": "Path to the lockfile to verify"
        }
      ],
      "options": [
        {
          "name": "root",
          "flag": "--root",
          "type": "directory_path",
          "description": "Root directory for member verification. Without this, only self-hash is checked."
        },
        {
          "name": "json",
          "flag": "--json",
          "type": "flag",
          "description": "Emit structured JSON output (default is human-readable)"
        },
        {
          "name": "no_witness",
          "flag": "--no-witness",
          "type": "flag",
          "description": "Suppress witness ledger recording for this run"
        },
        {
          "name": "strict",
          "flag": "--strict",
          "type": "flag",
          "description": "Promote VERIFY_PARTIAL to VERIFY_FAILED"
        }
      ],
      "exit_codes": {
        "0": {
          "meaning": "VERIFY_OK",
          "domain": "positive"
        },
        "1": {
          "meaning": "VERIFY_FAILED or VERIFY_PARTIAL",
          "domain": "negative"
        },
        "2": {
          "meaning": "REFUSAL",
          "domain": "error"
        }
      },
      "refusals": [
        {
          "code": "E_IO",
          "message": "Cannot read lockfile",
          "action": "check_path"
        },
        {
          "code": "E_BAD_LOCKFILE",
          "message": "Malformed JSON or missing required fields",
          "action": "regenerate_lockfile"
        },
        {
          "code": "E_UNSUPPORTED_VERSION",
          "message": "Lockfile version not supported",
          "action": "upgrade_tool"
        },
        {
          "code": "E_ROOT_NOT_FOUND",
          "message": "Root directory does not exist",
          "action": "check_path"
        },
        {
          "code": "E_UNKNOWN_ALGORITHM",
          "message": "Unrecognized hash algorithm prefix",
          "action": "regenerate_lockfile"
        }
      ]
    }
  ],

  "exit_codes": {
    "0": {
      "meaning": "LOCK_CREATED",
      "domain": "positive"
    },
    "1": {
      "meaning": "LOCK_PARTIAL",
      "domain": "negative"
    },
    "2": {
      "meaning": "REFUSAL / CLI error / witness internal error",
      "domain": "error"
    }
  },

  "refusals": [
    {
      "code": "E_EMPTY",
      "message": "No input records",
      "action": "run_upstream",
      "tool": "vacuum"
    },
    {
      "code": "E_BAD_INPUT",
      "message": "Invalid JSONL or unknown record version",
      "action": "rerun_pipeline_or_pack_seal",
      "input_mode": "pipeline_only",
      "standalone_alternative": "pack seal"
    },
    {
      "code": "E_MISSING_HASH",
      "message": "Records lack bytes_hash",
      "action": "run_upstream",
      "tool": "hash"
    }
  ],

  "capabilities": {
    "formats": [
      "jsonl"
    ],
    "profile_aware": false,
    "streaming": false,
    "witness": {
      "ambient_recording": "enabled_by_default",
      "query_subcommands": "available",
      "no_witness_flag": "suppresses_recording"
    }
  },

  "pipeline": {
    "mode": "pipeline_only",
    "input": "versioned JSONL records from upstream tools",
    "example_pipeline": "vacuum <path> | hashbytes | lock --dataset-id \"<dataset>\" > dataset.lock.json",
    "standalone_alternative": "pack seal",
    "upstream": [
      "vacuum",
      "hash",
      "fingerprint"
    ],
    "downstream": [
      "pack"
    ]
  }
}