etch-record 0.1.0__py3-none-any.whl

etch_record/__init__.py

@@ -0,0 +1,3 @@
+"""etch-record: CLI helper for signing arbitrary events into your Etch chain."""
+
+__version__ = "0.1.0"

etch_record/cli.py

@@ -0,0 +1,619 @@
+"""CLI entry point for etch-record.
+
+Usage:
+  etch-record "description of the event" [OPTIONS]
+
+Only one event_type value is accepted by the Etch server enum today for
+arbitrary user-recorded events: "tool_call". Anything else silently
+drops server-side (this is the exact bug the /docs/quickstart Common
+Gotchas section warns about). So we hardcode "tool_call" and let
+callers differentiate via --tags + --evidence-json.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .config import ConfigError, load
+from .governance_client import GovernanceError, record_governance
+from .mcp_client import McpError, extract_event_id, record_event
+from .rate_limit import check_and_record
+
+
+_LARGE_ARG_THRESHOLD_CHARS = 4096
+
+
+def _default_session_id() -> str:
+    """Group events emitted on the same UTC calendar day into one session."""
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    return f"etch-record-{today}"
+
+
+def _parse_tags(raw: str | None) -> list[str]:
+    if not raw:
+        return []
+    return [t.strip() for t in raw.split(",") if t.strip()]
+
+
+def _load_evidence(
+    evidence_json: str | None,
+    evidence_file: Path | None,
+) -> dict:
+    if evidence_json and evidence_file:
+        raise click.UsageError(
+            "Pass only one of --evidence-json or --evidence-file, not both.",
+        )
+    if evidence_json:
+        try:
+            parsed = json.loads(evidence_json)
+        except json.JSONDecodeError as exc:
+            raise click.UsageError(
+                f"--evidence-json is not valid JSON: {exc}",
+            ) from exc
+        if not isinstance(parsed, dict):
+            raise click.UsageError("--evidence-json must be a JSON object.")
+        return parsed
+    if evidence_file:
+        try:
+            parsed = json.loads(evidence_file.read_text())
+        except (OSError, json.JSONDecodeError) as exc:
+            raise click.UsageError(
+                f"--evidence-file could not be loaded: {exc}",
+            ) from exc
+        if not isinstance(parsed, dict):
+            raise click.UsageError("--evidence-file must contain a JSON object.")
+        return parsed
+    return {}
+
+
+def _resolve_text_source(
+    inline_value: str | None,
+    file_path: Path | None,
+    field_name: str,
+) -> str:
+    """Load a text field from either an inline CLI arg or a file.
+
+    Symmetric with _load_evidence: exactly one may be set.
+    File contents are stripped of ONE trailing newline (a common editor
+    artifact) and otherwise passed through verbatim.
+    """
+    if inline_value and file_path:
+        raise click.UsageError(
+            f"Pass only one of --{field_name} or --{field_name}-file, not both.",
+        )
+    if file_path is not None:
+        try:
+            text = file_path.read_text()
+        except OSError as exc:
+            raise click.UsageError(
+                f"--{field_name}-file could not be loaded: {exc}",
+            ) from exc
+        if text.endswith("\n"):
+            text = text[:-1]
+        return text
+    return inline_value or ""
+
+
+def _resolve_description(positional: str, file_path: Path | None) -> str:
+    """Description resolution with click's required-positional in mind.
+
+    - No file: positional is the description (legacy behavior).
+    - With file: file content becomes the description; positional stays
+      as a short human label captured in the Layer A Bash-hook trace
+      but is NOT the recorded payload.
+    """
+    if file_path is None:
+        return positional
+    try:
+        text = file_path.read_text()
+    except OSError as exc:
+        raise click.UsageError(
+            f"--description-file could not be loaded: {exc}",
+        ) from exc
+    if text.endswith("\n"):
+        text = text[:-1]
+    return text
+
+
+def _resolve_action_time(
+    action_time: str | None,
+    action_time_now: bool,
+) -> str | None:
+    """Normalize the real-world action timestamp for the evidence dict.
+
+    Returns an ISO-8601 UTC string ("YYYY-MM-DDTHH:MM:SSZ") or None
+    when neither flag is set. Rejects passing both at once.
+
+    Accepts any ISO-8601 form recognized by datetime.fromisoformat
+    (Python 3.10+ compatible - Z suffix is normalized to +00:00 first).
+    A timezone MUST be present; a naive datetime is rejected because
+    "action_time_utc without a timezone" is ambiguous and worse than
+    no action_time at all.
+    """
+    if action_time and action_time_now:
+        raise click.UsageError(
+            "Pass only one of --action-time or --action-time-now, not both.",
+        )
+    if action_time_now:
+        now_utc = datetime.now(timezone.utc)
+        return now_utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+    if action_time is None:
+        return None
+    raw = action_time.strip()
+    if not raw:
+        raise click.UsageError("--action-time was empty.")
+    # Python 3.10 fromisoformat does NOT recognize the Z suffix. Normalize.
+    normalized = raw[:-1] + "+00:00" if raw.endswith("Z") else raw
+    try:
+        dt = datetime.fromisoformat(normalized)
+    except ValueError as exc:
+        raise click.UsageError(
+            f"--action-time is not a valid ISO-8601 timestamp: {exc}. "
+            "Examples: 2026-07-28T14:03:00Z, 2026-07-28T19:33:00+05:30.",
+        ) from exc
+    if dt.tzinfo is None:
+        raise click.UsageError(
+            "--action-time must include a timezone (e.g. 'Z' suffix or "
+            "+HH:MM offset). Naive timestamps are ambiguous.",
+        )
+    utc_dt = dt.astimezone(timezone.utc)
+    return utc_dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _maybe_warn_large_arg(name: str, value: str) -> None:
+    """Print a stderr warning when a text arg passed via CLI is large.
+
+    Large CLI args are a footgun: Claude Code's Bash-hook records the
+    invocation with its arguments hashed into an audit event, which
+    doubles the payload on the chain and (in multi-tenant deploys)
+    can cross tenant boundaries. --reasoning-file / --description-file
+    bypass this. This warning nudges users toward those flags for
+    sensitive content without blocking legitimate use.
+    """
+    if len(value) > _LARGE_ARG_THRESHOLD_CHARS:
+        click.echo(
+            f"etch-record: warning: --{name} is {len(value)} chars via CLI "
+            f"argv. Consider --{name}-file for large or sensitive content; "
+            f"CLI args are captured verbatim by shell-hook auditors.",
+            err=True,
+        )
+
+
+@click.command(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help=(
+        "Sign one event into your Etch chain from the command line.\n\n"
+        "Every call becomes a signed record_event on your Etch project."
+        " Requires ETCH_PROJECT_ID and ETCH_APP_TOKEN in the environment."
+    ),
+)
+@click.argument("description", type=str)
+@click.option(
+    "--tags",
+    "tags_raw",
+    type=str,
+    default=None,
+    help="Comma-separated tags (e.g. research,x,launch). Become the event's entities.",
+)
+@click.option(
+    "--evidence-json",
+    type=str,
+    default=None,
+    help="Inline JSON object with extra structured evidence.",
+)
+@click.option(
+    "--evidence-file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Path to a JSON file containing an evidence object.",
+)
+@click.option(
+    "--session-id",
+    type=str,
+    default=None,
+    help=(
+        "Group this event with others under the same session id. "
+        "Default: etch-record-YYYY-MM-DD (current UTC date)."
+    ),
+)
+@click.option(
+    "--reasoning",
+    type=str,
+    default=None,
+    help="Optional freeform reasoning string.",
+)
+@click.option(
+    "--reasoning-file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help=(
+        "Path to a text file whose contents become the reasoning field. "
+        "Use this instead of --reasoning for large or sensitive content: "
+        "CLI args are captured verbatim by shell-hook auditors."
+    ),
+)
+@click.option(
+    "--description-file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help=(
+        "Path to a text file whose contents OVERRIDE the description "
+        "positional argument. When set, the description positional "
+        "argument may be a short label like 'from-file'; the file "
+        "contents become the actual description in the event. Same "
+        "safety motivation as --reasoning-file."
+    ),
+)
+@click.option(
+    "--from-hook",
+    "from_hook",
+    type=str,
+    default=None,
+    help=(
+        "Reference id of the Claude Code hook (Layer A) event this "
+        "semantic event corresponds to. Adds `layer_a_ref` to evidence "
+        "and the `hook_bound` tag for explicit two-layer bind. Env "
+        "fallback: ETCH_HOOK_TOOL_USE_ID."
+    ),
+)
+@click.option(
+    "--action-time",
+    "action_time",
+    type=str,
+    default=None,
+    help=(
+        "Real-world timestamp of the action being recorded, ISO-8601 "
+        "with timezone (e.g. 2026-07-28T14:03:00Z). Adds "
+        "`action_time_utc` to evidence so downstream audit reconstructs "
+        "when the action HAPPENED, not just when it was signed. Use for "
+        "after-the-fact signing where signing-time and action-time differ."
+    ),
+)
+@click.option(
+    "--action-time-now",
+    is_flag=True,
+    default=False,
+    help=(
+        "Shortcut for --action-time set to the current UTC. Useful when "
+        "signing immediately after the action."
+    ),
+)
+@click.option(
+    "--force-no-rate-limit",
+    is_flag=True,
+    default=False,
+    help=(
+        "Bypass the client-side sliding-window rate limit for this "
+        "invocation. Use only for legitimate batch or backfill flows."
+    ),
+)
+@click.option(
+    "--failed",
+    is_flag=True,
+    default=False,
+    help="Mark the event as unsuccessful (success=false).",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Print the payload that would be sent, do not call Etch.",
+)
+# ---------------------------------------------------------------------------
+# Wave 1 #1 (2026-08-01) — extended governance schema flags.
+# When any of these is set, the CLI makes TWO calls:
+#   1. mcp_client.record_event → creates the base OSS event (unchanged)
+#   2. governance_client.record_governance → attaches a signed
+#      governance sub-record to the Etch parallel chain, cross-
+#      referencing the OSS event by id
+# When none are set, the CLI behaves exactly as before (single
+# record_event call). Zero behavior change for callers that don't
+# opt in.
+# ---------------------------------------------------------------------------
+@click.option(
+    "--policy-hash",
+    "policy_hash",
+    type=str,
+    default=None,
+    help=(
+        "Wave 1 #1 governance: SHA-256 hash of the governance policy "
+        "under which this decision was evaluated. Must be 'sha256:<64-hex>' "
+        "shape. Triggers a second call to /v1/etch-chain/governance-record "
+        "on the Etch chain."
+    ),
+)
+@click.option(
+    "--authority-file",
+    "authority_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help=(
+        "Wave 1 #1 governance: path to a JSON file describing the "
+        "approving authority: {identity, scope, expires_at}. See "
+        "docs/wave-1-1.md for the schema."
+    ),
+)
+@click.option(
+    "--assumptions-file",
+    "assumptions_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help=(
+        "Wave 1 #1 governance: path to a JSON file listing assumptions "
+        "accepted when reaching the decision. Each entry is "
+        "{claim, source_ref}."
+    ),
+)
+@click.option(
+    "--uncertainty",
+    "uncertainty",
+    type=str,
+    default=None,
+    help=(
+        "Wave 1 #1 governance: uncertainty attached to the decision, "
+        "given as 'confidence:basis' (e.g. "
+        "'0.87:evidence-hash-lookup-match-rate'). Confidence must be "
+        "[0.0, 1.0]. For richer shapes use --uncertainty-file."
+    ),
+)
+@click.option(
+    "--uncertainty-file",
+    "uncertainty_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help=(
+        "Wave 1 #1 governance: path to a JSON file with the full "
+        "uncertainty object: {confidence, basis}."
+    ),
+)
+@click.option(
+    "--invalidation-file",
+    "invalidation_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help=(
+        "Wave 1 #1 governance: path to a JSON file listing conditions "
+        "under which the approval would have been invalidated. Each "
+        "entry is {\"if\": ..., \"then\": ...}."
+    ),
+)
+@click.version_option(__version__, prog_name="etch-record")
+def main(
+    description: str,
+    tags_raw: str | None,
+    evidence_json: str | None,
+    evidence_file: Path | None,
+    session_id: str | None,
+    reasoning: str | None,
+    reasoning_file: Path | None,
+    description_file: Path | None,
+    from_hook: str | None,
+    action_time: str | None,
+    action_time_now: bool,
+    force_no_rate_limit: bool,
+    failed: bool,
+    dry_run: bool,
+    policy_hash: str | None,
+    authority_file: Path | None,
+    assumptions_file: Path | None,
+    uncertainty: str | None,
+    uncertainty_file: Path | None,
+    invalidation_file: Path | None,
+) -> None:
+    tags = _parse_tags(tags_raw)
+    evidence = _load_evidence(evidence_json, evidence_file)
+    session = session_id or _default_session_id()
+
+    # Resolve reasoning from either inline arg or file (symmetric with
+    # --evidence-json / --evidence-file split; both flags are optional).
+    resolved_reasoning = _resolve_text_source(
+        reasoning, reasoning_file, "reasoning",
+    )
+    # Description is special: the positional CLI arg is REQUIRED by click,
+    # so users cannot omit it. When --description-file is passed, the file
+    # content becomes the actual event description; the positional serves
+    # as a short human label the user sees in shell history + the Layer A
+    # Bash-hook event, keeping the sensitive payload off argv.
+    resolved_description = _resolve_description(description, description_file)
+
+    # Sensitive-arg guard: warn (do not block) on oversized inline
+    # text passed via CLI argv. Skipped when the file variant was used.
+    if reasoning and not reasoning_file:
+        _maybe_warn_large_arg("reasoning", reasoning)
+    if description and not description_file:
+        _maybe_warn_large_arg("description", description)
+
+    # Two-layer bind: --from-hook (or env fallback) adds an explicit
+    # cross-reference to the Layer A (mechanical) hook event.
+    hook_ref = from_hook or os.environ.get("ETCH_HOOK_TOOL_USE_ID", "").strip()
+    if hook_ref:
+        evidence = {**evidence, "layer_a_ref": hook_ref}
+        if "hook_bound" not in tags:
+            tags = [*tags, "hook_bound"]
+
+    # Real-world action timestamp (--action-time / --action-time-now):
+    # closes the drift between "when it happened" and "when I signed it".
+    resolved_action_time = _resolve_action_time(action_time, action_time_now)
+    if resolved_action_time is not None:
+        evidence = {**evidence, "action_time_utc": resolved_action_time}
+
+    arguments = {
+        "event_type": "tool_call",
+        "session_id": session,
+        "entities": tags,
+        "description": resolved_description,
+        "reasoning": resolved_reasoning,
+        "evidence": evidence,
+        "success": not failed,
+    }
+
+    if dry_run:
+        click.echo(
+            json.dumps(
+                {"method": "tools/call", "name": "record_event", "arguments": arguments},
+                indent=2,
+                sort_keys=True,
+            ),
+        )
+        return
+
+    # Client-side rate limit BEFORE config load: a rate-limited caller
+    # should get a clear message, not a config error, when their env
+    # is not yet set up. Disabled by --force-no-rate-limit or by
+    # ETCH_RATE_LIMIT_PER_MINUTE=0.
+    if not force_no_rate_limit:
+        allowed, count, limit = check_and_record()
+        if not allowed:
+            click.echo(
+                f"etch-record: rate limit hit ({count}/{limit} events in "
+                f"the last 60s). Wait a few seconds and retry, or pass "
+                f"--force-no-rate-limit for legitimate batch use. Adjust "
+                f"the ceiling with ETCH_RATE_LIMIT_PER_MINUTE.",
+                err=True,
+            )
+            sys.exit(4)
+
+    try:
+        cfg = load()
+    except ConfigError as exc:
+        click.echo(str(exc), err=True)
+        sys.exit(1)
+
+    try:
+        body = record_event(cfg, arguments)
+    except McpError as exc:
+        click.echo(f"etch-record: {exc}", err=True)
+        sys.exit(2)
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"etch-record: unexpected error: {exc}", err=True)
+        sys.exit(3)
+
+    event_id = extract_event_id(body) or "?"
+    click.echo(f"OK  session={session}  event_id={event_id}")
+
+    # Wave 1 #1 — if any governance flag was set, assemble the
+    # governance object and POST it to the Etch chain endpoint.
+    governance = _assemble_governance_from_flags(
+        policy_hash=policy_hash,
+        authority_file=authority_file,
+        assumptions_file=assumptions_file,
+        uncertainty=uncertainty,
+        uncertainty_file=uncertainty_file,
+        invalidation_file=invalidation_file,
+    )
+    if governance is None:
+        return
+
+    try:
+        result = record_governance(cfg, event_id, governance)
+    except GovernanceError as exc:
+        click.echo(f"etch-record: governance-record: {exc}", err=True)
+        # Base event was recorded successfully; the governance sub-record
+        # failed. Exit non-zero so shell callers can catch it, but keep
+        # the earlier OK line above so the caller has the event_id to
+        # retry against.
+        sys.exit(5)
+
+    click.echo(
+        f"OK  governance_seq={result.etch_chain_seq}  "
+        f"governance_hash={result.governance_hash}",
+    )
+
+
+def _assemble_governance_from_flags(
+    policy_hash: str | None,
+    authority_file: Path | None,
+    assumptions_file: Path | None,
+    uncertainty: str | None,
+    uncertainty_file: Path | None,
+    invalidation_file: Path | None,
+) -> dict | None:
+    """Compose the governance object from CLI flags, or return None if
+    none of them are set (signals: skip the second API call)."""
+    if not any((
+        policy_hash, authority_file, assumptions_file,
+        uncertainty, uncertainty_file, invalidation_file,
+    )):
+        return None
+
+    if uncertainty and uncertainty_file:
+        raise click.UsageError(
+            "Pass only one of --uncertainty or --uncertainty-file, "
+            "not both.",
+        )
+
+    gov: dict = {}
+    if policy_hash:
+        gov["policy_hash"] = policy_hash
+    if authority_file is not None:
+        gov["authority"] = _read_json_object(authority_file, "--authority-file")
+    if assumptions_file is not None:
+        gov["assumptions"] = _read_json_list(
+            assumptions_file, "--assumptions-file",
+        )
+    if uncertainty is not None:
+        gov["uncertainty"] = _parse_uncertainty_inline(uncertainty)
+    elif uncertainty_file is not None:
+        gov["uncertainty"] = _read_json_object(
+            uncertainty_file, "--uncertainty-file",
+        )
+    if invalidation_file is not None:
+        gov["invalidation_conditions"] = _read_json_list(
+            invalidation_file, "--invalidation-file",
+        )
+    return gov
+
+
+def _read_json_object(path: Path, flag_name: str) -> dict:
+    try:
+        parsed = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        raise click.UsageError(
+            f"{flag_name} could not be loaded: {exc}",
+        ) from exc
+    if not isinstance(parsed, dict):
+        raise click.UsageError(f"{flag_name} must be a JSON object.")
+    return parsed
+
+
+def _read_json_list(path: Path, flag_name: str) -> list:
+    try:
+        parsed = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        raise click.UsageError(
+            f"{flag_name} could not be loaded: {exc}",
+        ) from exc
+    if not isinstance(parsed, list):
+        raise click.UsageError(f"{flag_name} must be a JSON array.")
+    return parsed
+
+
+def _parse_uncertainty_inline(raw: str) -> dict:
+    """Parse '<confidence>:<basis>' into {confidence, basis}."""
+    if ":" not in raw:
+        raise click.UsageError(
+            "--uncertainty must be 'confidence:basis' (e.g. "
+            "'0.87:evidence-hash-match-rate').",
+        )
+    conf_str, basis = raw.split(":", 1)
+    try:
+        confidence = float(conf_str)
+    except ValueError as exc:
+        raise click.UsageError(
+            f"--uncertainty confidence must be a float: {exc}",
+        ) from exc
+    if not (0.0 <= confidence <= 1.0):
+        raise click.UsageError(
+            "--uncertainty confidence must be in [0.0, 1.0].",
+        )
+    basis = basis.strip()
+    if not basis:
+        raise click.UsageError("--uncertainty basis must be non-empty.")
+    return {"confidence": confidence, "basis": basis}

etch_record/config.py

@@ -0,0 +1,47 @@
+"""Config resolution: env vars first, no on-disk config file for MVP.
+
+Missing env vars raise a `ConfigError` the CLI catches and turns into
+a friendly stderr message + exit code 1.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Config:
+    project_id: str
+    app_token: str
+    base_url: str
+
+
+def load() -> Config:
+    project_id = os.environ.get("ETCH_PROJECT_ID", "").strip()
+    app_token = os.environ.get("ETCH_APP_TOKEN", "").strip()
+    base_url = os.environ.get("ETCH_BASE_URL", "https://etch.systems").rstrip("/")
+
+    missing = []
+    if not project_id:
+        missing.append("ETCH_PROJECT_ID")
+    if not app_token:
+        missing.append("ETCH_APP_TOKEN")
+    if missing:
+        raise ConfigError(
+            "Missing required environment variable(s): "
+            + ", ".join(missing)
+            + "\nSet in your shell rc (~/.zshrc):\n"
+            + "  export ETCH_PROJECT_ID=your_project_id\n"
+            + "  export ETCH_APP_TOKEN=wm_your_app_token\n"
+        )
+
+    return Config(
+        project_id=project_id,
+        app_token=app_token,
+        base_url=base_url,
+    )

etch_record/governance_client.py

@@ -0,0 +1,146 @@
+"""HTTP client for Wave 1 #1 governance-record endpoint (2026-08-01).
+
+Companion to mcp_client.py. Where mcp_client speaks MCP StreamableHTTP
+to invoke tools like record_event, this module speaks plain HTTP to
+Etch's own compliance surface (currently: POST
+/v1/etch-chain/governance-record).
+
+Kept as a separate module so the CLI can compose:
+  1. mcp_client.record_event(...) → get OSS event_id
+  2. governance_client.record_governance(cfg, event_id, gov) → attach
+     signed compliance metadata to the Etch parallel chain
+
+Both calls hit etch.systems with the same Bearer token, so a client
+that can call one can call the other.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import httpx
+
+from .config import Config
+
+
+_TIMEOUT_S = 30.0
+
+
+class GovernanceError(RuntimeError):
+    """Raised when the governance-record HTTP call fails in a way the
+    CLI should surface with a friendly stderr message + exit code."""
+
+
+@dataclass(frozen=True)
+class GovernanceResult:
+    """Response payload from a successful POST
+    /v1/etch-chain/governance-record. All fields come from the server;
+    the client does not compute anything locally."""
+
+    etch_chain_seq: int
+    etch_row_id: str
+    governance_hash: str
+    oss_event_id_ref: str
+    recorded_at: str
+
+
+def record_governance(
+    cfg: Config,
+    oss_event_id: str,
+    governance: dict,
+    client: Optional[httpx.Client] = None,
+) -> GovernanceResult:
+    """POST /v1/etch-chain/governance-record.
+
+    Args:
+      cfg: loaded Config (has base_url + app_token).
+      oss_event_id: the event_id returned by mcp_client.record_event.
+      governance: assembled governance object (validated server-side
+        via Pydantic; local validation would drift and is skipped).
+      client: optional httpx.Client for dependency injection. Tests
+        pass a MockTransport-backed client. Prod passes None; the
+        function creates a default client bounded by _TIMEOUT_S.
+
+    Returns:
+      GovernanceResult on 200.
+
+    Raises:
+      GovernanceError on any non-200 or transport failure. Message
+      surfaces the server's error code + hint when the response body
+      is a valid JSON error envelope.
+    """
+    url = f"{cfg.base_url}/v1/etch-chain/governance-record"
+    body = {
+        "oss_event_id": oss_event_id,
+        "governance": governance,
+    }
+    headers = {
+        "Authorization": f"Bearer {cfg.app_token}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+
+    owned_client = client is None
+    if owned_client:
+        client = httpx.Client(timeout=_TIMEOUT_S)
+
+    try:
+        try:
+            resp = client.post(url, json=body, headers=headers)
+        except httpx.HTTPError as exc:
+            raise GovernanceError(
+                f"transport failed while calling {url}: {exc}",
+            ) from exc
+    finally:
+        if owned_client:
+            client.close()
+
+    if resp.status_code == 200:
+        try:
+            payload = resp.json()
+        except ValueError as exc:
+            raise GovernanceError(
+                f"200 response was not valid JSON: {exc}",
+            ) from exc
+        return GovernanceResult(
+            etch_chain_seq=int(payload["etch_chain_seq"]),
+            etch_row_id=str(payload["etch_row_id"]),
+            governance_hash=str(payload["governance_hash"]),
+            oss_event_id_ref=str(payload["oss_event_id_ref"]),
+            recorded_at=str(payload["recorded_at"]),
+        )
+
+    # Non-200 — try to parse the server's JSON error envelope.
+    try:
+        err_payload = resp.json()
+    except ValueError:
+        raise GovernanceError(
+            f"HTTP {resp.status_code} with non-JSON body: "
+            f"{resp.text[:200]!r}",
+        )
+
+    err_code = err_payload.get("error", "unknown_error")
+    if err_code == "insufficient_scope":
+        raise GovernanceError(
+            f"insufficient_scope: your app token needs "
+            f"{err_payload.get('required_scope')!r} but has "
+            f"{err_payload.get('token_scopes')}. Mint a new token "
+            f"with mcp:write scope.",
+        )
+    if err_code == "validation_failed":
+        details = err_payload.get("details", [])
+        summary = "; ".join(
+            f"{d.get('loc')}: {d.get('msg')}" for d in details
+        )
+        raise GovernanceError(
+            f"governance object failed validation: {summary}",
+        )
+    if err_code == "invalid_json_body":
+        raise GovernanceError(
+            "server rejected the request body as invalid JSON",
+        )
+
+    raise GovernanceError(
+        f"HTTP {resp.status_code}: {err_code}",
+    )

etch_record/mcp_client.py

@@ -0,0 +1,178 @@
+"""Minimal MCP client for the single flow we need: post one `record_event`.
+
+Handles the three-step MCP dance:
+  1. POST /mcp   {method: "initialize"}         -> session_id in response header
+  2. POST /mcp   {method: "notifications/initialized"}
+  3. POST /mcp   {method: "tools/call", name: "record_event", arguments: {...}}
+
+Session ID is per-invocation. We do NOT persist it across CLI runs -
+each `etch-record` call is a fresh session. That is O(1) events per
+invocation, which is fine for CLI usage; a daemon-style caller would
+want to keep the session open.
+
+Response format: the Etch /mcp endpoint uses the MCP StreamableHTTP
+transport, which serves responses as text/event-stream (SSE) frames
+containing the JSON-RPC body inside a `data:` line. For a single
+tools/call there is exactly one message frame per response, so we
+extract the data payload and parse it as JSON.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from .config import Config
+
+
+class McpError(RuntimeError):
+    pass
+
+
+_PROTOCOL_VERSION = "2025-11-05"
+_TIMEOUT_SECONDS = 15.0
+
+
+def _parse_mcp_body(response: httpx.Response) -> dict:
+    """Return the JSON-RPC body from an MCP response.
+
+    Handles both content types the MCP StreamableHTTP transport spec
+    permits:
+      - application/json (plain JSON body)
+      - text/event-stream (SSE frames; the JSON is inside data: lines)
+
+    For SSE, we concatenate all `data:` lines in the response (per the
+    SSE spec: a single message split across multiple data lines is
+    reassembled by joining with newlines) and parse the result.
+    Returns the parsed JSON-RPC message dict.
+    """
+    content_type = (response.headers.get("content-type") or "").lower()
+    text = response.text
+
+    is_sse = (
+        "text/event-stream" in content_type
+        or text.lstrip().startswith("event:")
+        or text.lstrip().startswith("data:")
+    )
+    if is_sse:
+        data_parts: list[str] = []
+        for raw in text.splitlines():
+            if raw.startswith("data:"):
+                # Per SSE spec: strip leading "data:" then a single
+                # optional space. Do not strip further whitespace so
+                # JSON with intentional leading spaces round-trips.
+                chunk = raw[len("data:"):]
+                if chunk.startswith(" "):
+                    chunk = chunk[1:]
+                data_parts.append(chunk)
+        if not data_parts:
+            raise McpError(
+                f"SSE response contained no data lines: {text[:200]!r}",
+            )
+        joined = "\n".join(data_parts)
+        try:
+            return json.loads(joined)
+        except json.JSONDecodeError as exc:
+            raise McpError(
+                f"SSE data was not valid JSON: {joined[:200]!r}",
+            ) from exc
+
+    # Plain JSON response.
+    try:
+        return response.json()
+    except json.JSONDecodeError as exc:
+        raise McpError(
+            f"non-JSON response ({content_type or 'no content-type'}): "
+            f"{text[:200]!r}",
+        ) from exc
+
+
+def extract_event_id(body: dict) -> str | None:
+    """Pull the Etch server's event_id out of a tools/call result body.
+
+    Etch's record_event tool returns a nested JSON string inside
+    result.content[0].text, shaped like:
+        {"event_id": "uuid", "status": "recorded"}
+    This peels the two layers and returns the inner event_id. Returns
+    None if the shape doesn't match (call sites should fall back to
+    the JSON-RPC message id or "?").
+    """
+    try:
+        content = body.get("result", {}).get("content") or []
+        if not content:
+            return None
+        first = content[0]
+        text = first.get("text") if isinstance(first, dict) else None
+        if not text:
+            return None
+        inner = json.loads(text)
+        eid = inner.get("event_id")
+        return str(eid) if eid is not None else None
+    except (json.JSONDecodeError, AttributeError, TypeError, IndexError):
+        return None
+
+
+def _headers_for(cfg: Config, mcp_session_id: str | None = None) -> dict[str, str]:
+    hdrs = {
+        "Authorization": f"Bearer {cfg.app_token}",
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+    }
+    if mcp_session_id:
+        hdrs["mcp-session-id"] = mcp_session_id
+    return hdrs
+
+
+def _initialize(client: httpx.Client, cfg: Config) -> str:
+    payload = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": _PROTOCOL_VERSION,
+            "capabilities": {},
+            "clientInfo": {"name": "etch-record", "version": "0.1.0"},
+        },
+    }
+    r = client.post("/mcp", headers=_headers_for(cfg), json=payload)
+    if r.status_code != 200:
+        raise McpError(f"initialize failed: {r.status_code} {r.text[:200]}")
+    sid = r.headers.get("mcp-session-id")
+    if not sid:
+        raise McpError("initialize response missing mcp-session-id header")
+    return sid
+
+
+def _notify_initialized(client: httpx.Client, cfg: Config, sid: str) -> None:
+    payload = {"jsonrpc": "2.0", "method": "notifications/initialized"}
+    r = client.post("/mcp", headers=_headers_for(cfg, sid), json=payload)
+    # 202 is the expected response for notifications; 200 also fine.
+    if r.status_code not in (200, 202):
+        raise McpError(
+            f"notifications/initialized failed: {r.status_code} {r.text[:200]}"
+        )
+
+
+def record_event(cfg: Config, arguments: dict[str, Any]) -> dict[str, Any]:
+    """Post one record_event tool call. Returns the parsed JSON result."""
+    with httpx.Client(base_url=cfg.base_url, timeout=_TIMEOUT_SECONDS) as client:
+        sid = _initialize(client, cfg)
+        _notify_initialized(client, cfg, sid)
+
+        payload = {
+            "jsonrpc": "2.0",
+            "id": 42,
+            "method": "tools/call",
+            "params": {"name": "record_event", "arguments": arguments},
+        }
+        r = client.post("/mcp", headers=_headers_for(cfg, sid), json=payload)
+        if r.status_code != 200:
+            raise McpError(
+                f"tools/call failed: {r.status_code} {r.text[:200]}"
+            )
+        body = _parse_mcp_body(r)
+        if "error" in body:
+            raise McpError(f"MCP error: {body['error']}")
+        return body

etch_record/rate_limit.py

@@ -0,0 +1,111 @@
+"""Client-side sliding-window rate limit for etch-record.
+
+Guards against tight-loop misuse (dev accidentally emits a hot loop) that
+would double-log through both the Claude Code Bash-invocation hook and
+the etch-record semantic event.
+
+Design choices:
+  - Sliding window, 60 seconds, event-count based.
+  - State persisted at ~/.etch-record/rate_state.json as a list of unix
+    timestamps. Prune older-than-window on every read.
+  - Fails OPEN: any state-file corruption or FS error is logged to
+    stderr and treated as "no prior events". Rate limit exists to catch
+    an accidental hot loop, not to be an authoritative security control;
+    a broken state file must never block a legitimate event.
+  - Default limit is 100 events/minute. Override via env
+    ETCH_RATE_LIMIT_PER_MINUTE (int; set to 0 to disable entirely).
+  - No inter-process locking. Concurrent invocations may double-count
+    slightly; the goal is order-of-magnitude protection, not exactness.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+_STATE_DIR = Path.home() / ".etch-record"
+_STATE_FILE = _STATE_DIR / "rate_state.json"
+_WINDOW_SECONDS = 60.0
+_DEFAULT_LIMIT_PER_MINUTE = 100
+
+
+def _resolve_limit() -> int:
+    """Return current per-minute limit. 0 or negative disables the check."""
+    raw = os.environ.get("ETCH_RATE_LIMIT_PER_MINUTE", "").strip()
+    if not raw:
+        return _DEFAULT_LIMIT_PER_MINUTE
+    try:
+        return int(raw)
+    except ValueError:
+        return _DEFAULT_LIMIT_PER_MINUTE
+
+
+def _load_timestamps(state_file: Path, now: float) -> list[float]:
+    """Load and prune stale timestamps. Fails open on any error."""
+    if not state_file.exists():
+        return []
+    try:
+        raw = json.loads(state_file.read_text())
+    except (OSError, json.JSONDecodeError):
+        # Corrupt or unreadable state file: treat as empty. Rate limit
+        # is best-effort; a broken state must never block a caller.
+        return []
+    if not isinstance(raw, list):
+        return []
+    cutoff = now - _WINDOW_SECONDS
+    result: list[float] = []
+    for item in raw:
+        try:
+            ts = float(item)
+        except (TypeError, ValueError):
+            continue
+        if ts >= cutoff:
+            result.append(ts)
+    return result
+
+
+def _write_timestamps(state_file: Path, timestamps: list[float]) -> None:
+    """Persist pruned timestamps. Fails silently if the FS refuses."""
+    try:
+        state_file.parent.mkdir(parents=True, exist_ok=True)
+        state_file.write_text(json.dumps(timestamps))
+    except OSError as exc:
+        # Never crash on rate-limit state persistence failure.
+        print(
+            f"etch-record: warning: could not persist rate-limit state "
+            f"({exc}). Rate limiting may be inaccurate.",
+            file=sys.stderr,
+        )
+
+
+def check_and_record(
+    now: float | None = None,
+    state_file: Path | None = None,
+    limit_per_minute: int | None = None,
+) -> tuple[bool, int, int]:
+    """Consume one slot from the sliding window.
+
+    Returns (allowed, count_in_window, limit). If allowed=False the
+    caller should refuse to submit the event. If limit<=0 the check is
+    disabled and this returns (True, 0, 0) without touching state.
+
+    Args exist for tests; production callers pass nothing.
+    """
+    limit = _resolve_limit() if limit_per_minute is None else limit_per_minute
+    if limit <= 0:
+        return True, 0, 0
+    now = time.time() if now is None else now
+    sf = state_file if state_file is not None else _STATE_FILE
+
+    timestamps = _load_timestamps(sf, now)
+    count_before = len(timestamps)
+    if count_before >= limit:
+        # At or over the limit; refuse. Do NOT write this timestamp,
+        # so the caller can retry after the window slides.
+        return False, count_before, limit
+    timestamps.append(now)
+    _write_timestamps(sf, timestamps)
+    return True, count_before + 1, limit

etch_record-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: etch-record
+Version: 0.1.0
+Summary: CLI helper: sign any event into your Etch audit chain from the command line.
+Author: Saravanan Jaichandaran
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# etch-record
+
+Small CLI helper. Signs any event into your Etch audit chain from the command line.
+
+Built for the marketing-agent workflow: every research call, draft generation, review decision, and outreach send emits a signed event. Also usable standalone for any local activity you want notarized.
+
+**Latest: v0.2.0** — Wave 1 #1 governance flags (`--policy-hash`, `--authority-file`, `--assumptions-file`, `--uncertainty`, `--uncertainty-file`, `--invalidation-file`) attach a signed governance sub-record on the Etch parallel chain. See [CHANGELOG.md](CHANGELOG.md).
+
+## Install
+
+```bash
+pip install etch-record
+```
+
+Or from a local checkout during development:
+
+```bash
+cd ~/etch-marketing/etch-record
+pip install -e .
+```
+
+## Configure
+
+Set three env vars in your shell rc (`~/.zshrc` or `~/.bashrc`):
+
+```bash
+export ETCH_PROJECT_ID="your_project_id"
+export ETCH_APP_TOKEN="wm_your_app_token"
+export ETCH_BASE_URL="https://etch.systems"   # default; override for local dev
+```
+
+Get `project_id` + `app_token` from your Etch signup provisioning page. `ETCH_BASE_URL` defaults to `https://etch.systems` if unset.
+
+## Use
+
+```bash
+# Simple event
+etch-record "posted X thread about Etch's audit chain"
+
+# With tags + evidence
+etch-record "researched contact via Gemini" \
+  --tags research,marketing \
+  --evidence-json '{"contact":"...","dossier_lines":247}'
+
+# Load evidence from a file
+etch-record "drafted 3 message variants" \
+  --tags draft,claude \
+  --evidence-file drafts_evidence.json
+
+# Group events under a session (default = today's ISO date)
+etch-record "approved draft v2" --session-id outreach-2026-07-26 --tags review,approved
+
+# Print what would be sent without hitting the API
+etch-record "dry run test" --dry-run
+```
+
+## Event shape
+
+Every call becomes a signed `record_event` MCP tool call on your Etch chain:
+
+- `event_type`: `"tool_call"` (only enum value that works for arbitrary marketing events)
+- `session_id`: `--session-id` OR auto-generated as `etch-record-YYYY-MM-DD`
+- `entities`: derived from `--tags`
+- `description`: your quoted string (positional arg)
+- `evidence`: from `--evidence-json` or `--evidence-file`
+- `success`: `true` unless `--failed`
+
+The Etch server appends to the SHA-256 Merkle chain, closes epochs at threshold (default 1024 events), hybrid-signs (Ed25519 + SLH-DSA-SHA2-128f), and optionally anchors to Sigstore Rekor + Bitcoin OpenTimestamps.
+
+## Verify
+
+Every event is verifiable offline forever:
+
+```bash
+etch-verify \
+  --base-url https://etch.systems \
+  --project-id your_project_id
+```
+
+## Governance metadata (Wave 1 #1, v0.2.0)
+
+Attach a signed governance sub-record to any event. Any of the five flags below triggers a second call to `POST /v1/etch-chain/governance-record` on your Etch base URL, which hashes the governance object canonically and signs it into the Etch parallel chain.
+
+```bash
+etch-record "KYC decision on customer ABC" \
+  --tags kyc,fintech,decision \
+  --policy-hash sha256:9f8c... \
+  --authority-file authority.json \
+  --uncertainty '0.87:hash-lookup-match-rate' \
+  --invalidation-file invalidation_conditions.json
+```
+
+`authority.json`:
+
+```json
+{
+  "identity": "compliance-officer@acme.example",
+  "scope": ["fintech-kyc-decisions"],
+  "expires_at": "2026-12-31T23:59:59Z"
+}
+```
+
+`invalidation_conditions.json`:
+
+```json
+[
+  {"if": "SOP hash changes", "then": "re-approve required"}
+]
+```
+
+Assumptions file uses the same shape:
+
+```json
+[
+  {"claim": "SOP v3.2 is current", "source_ref": "doc_hash:xyz"}
+]
+```
+
+Output when both calls succeed:
+
+```
+OK  session=etch-record-2026-08-01  event_id=abc-def-123
+OK  governance_seq=1  governance_hash=sha256:xyz...
+```
+
+The base event was recorded via the OSS chain; the governance sub-record was signed into the Etch parallel chain and cross-references the event by ID. Both chains verify offline via `etch-verify` (OSS) and `etch-chain-verify` (Etch).
+
+## Exit codes
+
+- `0` success (including two-call success when governance flags were set)
+- `1` config error (missing env vars)
+- `2` MCP `record_event` error
+- `3` unexpected exception
+- `4` rate limit (client-side sliding window)
+- `5` governance sub-record failed — the base event was recorded successfully; use the printed `event_id` to retry the governance call

etch_record-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+etch_record/__init__.py,sha256=25j-Ap7qWSelGbbrzdw-La0SRLXDWcPQTSSvkcZB8B8,104
+etch_record/cli.py,sha256=eAtYvOiOe7lhhVaD_cV7qcYQ4M3M-MWgHITQOcHI4zo,21204
+etch_record/config.py,sha256=HIVK0T4eptS9P09mCpHuQspygT5pN7WA-56RA-O57JA,1213
+etch_record/governance_client.py,sha256=Y9LRDDospH8xkFE8T6Zo1C_1GlvyVB3hjwKUZfSEPgk,4678
+etch_record/mcp_client.py,sha256=idPLPqFteC1l7LUJuM8uOspA-VHkqIip4QtbAuej-nI,6335
+etch_record/rate_limit.py,sha256=0wqo0_50UKTSaegKXFYc0WXho3SsK41GJUOZCpwasko,3960
+etch_record-0.1.0.dist-info/METADATA,sha256=mzP4IgCAteYTFE7T7xC1URW2zbelTaYiKo50ikXMgWc,4590
+etch_record-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+etch_record-0.1.0.dist-info/entry_points.txt,sha256=N1EfY2v1MXaRlLkpNIXwt-jSh4aBKqabqpNtrHa_VHQ,53
+etch_record-0.1.0.dist-info/licenses/LICENSE,sha256=YvYKNXVQm7ccJcHd0CzLJC9Ma37bdLeC03HZ6_K_v3k,1079
+etch_record-0.1.0.dist-info/RECORD,,

etch_record-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

etch_record-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+etch-record = etch_record.cli:main

etch_record-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saravanan Jaichandaran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.