Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 28 additions & 3 deletions kits/profile-dev-kit/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ the required environment keys are present (key names only, never values).

Status: Story 5.2. Entry workflows `verify-change`, `read-report`,
`ratify-inventory`, `declare-non-applicability`, `record-approval-decision`,
`approve-change` and `read-approval`; tools `profile_preflight`,
`approve-change`, `read-approval` and `publish-reverification`; tools `profile_preflight`,
`profile_ratify_inventory`, `profile_bind_inventory`, `profile_record_change`,
`profile_derive_impact`, `profile_open_attempt`, `profile_run_gate`,
`profile_run_review`, `profile_capture_evidence`, `profile_record_report`,
`profile_read_report`, `profile_declare_non_applicability`,
`profile_read_report`, `profile_read_reverification`, `profile_declare_non_applicability`,
`profile_record_approval_decision`, `profile_approve_change` and
`profile_read_approval`.

Expand All @@ -24,8 +24,11 @@ python/beddel_profile_dev/tools/approval.py
Approval verification, persistence and read-back
python/beddel_profile_dev/tools/approval_decision.py
Approval decision transport
python/beddel_profile_dev/tools/publication.py
Read-only Re-verification copy source
workflows/ entry workflows, including
record-approval-decision and read-approval
record-approval-decision, read-approval and
publish-reverification
tests/ kit tests (no network, no real credential)
```

Expand Down Expand Up @@ -401,3 +404,25 @@ then `decision.commit_invalid`, `decision.unreachable`, `decision.absent`,
Every refusal raises `PROFILE_APPROVAL_REFUSED` and writes nothing. An invalid
repository path or records root keeps `PROFILE_REPOSITORY_INVALID`.
Ratification and Approval remain separate human acts.

## Re-verification copy (Story 7.1b)

`publish-reverification` takes `repo_path` and `change_id`. It first invokes
`profile_read_reverification`, which is read-only and refuses in this order:
`id.invalid`, `change.unrecorded`, `report.malformed`, `report.absent`,
`reverification.not_recorded` for an older schema,
`report.malformed` for an invalid latest record, `digest.mismatch`, and
`reverification.not_recorded` for a non-recorded status. Every refusal raises `PROFILE_PUBLICATION_REFUSED` and
leaves the records tree unchanged. The returned `reverification` value is the
whole object parsed from the latest stored Report; it is not rebuilt.

The workflow's copy step is skip-on-error. A failed copy appears only in the
run's `_absorbed_errors` as its step identity and stable error code. It never
changes the Verification Report or creates a publication record. The tracked
workflow uses the neutral key `copy_destination`, the placeholder endpoint
`https://copy-destination.invalid/mcp`, the placeholder tool `write_copy` and
the `entry` argument. The operator copy, kept outside every repository,
replaces those placeholders, adds any literal arguments and the matching
qualified `allowed_tools` entry. Consent is obtained outside a run with
`python -m beddel_protocol_mcp.authorize`. Nothing returned by the copy is
read back or stored.
9 changes: 9 additions & 0 deletions kits/profile-dev-kit/kit.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,10 @@ tools:
target: "beddel_profile_dev.tools.report:profile_read_report"
description: "Read the latest persisted Verification Report and its append-only history"
category: profile
- name: profile_read_reverification
target: "beddel_profile_dev.tools.publication:profile_read_reverification"
description: "Read the recorded Re-verification entry of the latest stored Report without writing records"
category: profile
- name: profile_declare_non_applicability
target: "beddel_profile_dev.tools.determine:profile_declare_non_applicability"
description: "Record the maintainer's determination that an obligation with an absent target is not applicable (transport only)"
Expand All @@ -101,6 +105,9 @@ workflows:
- name: read-report
path: workflows/read-report.yaml
description: Reads the latest persisted Verification Report and its history without running verification or writing records
- name: publish-reverification
path: workflows/publish-reverification.yaml
description: Publishes a one-way copy of the recorded Re-verification entry through the configured MCP destination; never blocks a verification
- name: ratify-inventory
path: workflows/ratify-inventory.yaml
description: Records the ratification of an inventory version
Expand Down Expand Up @@ -145,6 +152,8 @@ targets:
target: "beddel_profile_dev.tools.report:profile_record_report"
- name: profile_read_report
target: "beddel_profile_dev.tools.report:profile_read_report"
- name: profile_read_reverification
target: "beddel_profile_dev.tools.publication:profile_read_reverification"
- name: profile_declare_non_applicability
target: "beddel_profile_dev.tools.determine:profile_declare_non_applicability"
- name: profile_approve_change
Expand Down
4 changes: 4 additions & 0 deletions kits/profile-dev-kit/python/beddel_profile_dev/_errors.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
"PROFILE_INVENTORY_INTEGRITY_BLOCK",
"PROFILE_INVENTORY_UNRATIFIED",
"PROFILE_PREFLIGHT_FAILED",
"PROFILE_PUBLICATION_REFUSED",
"PROFILE_RATIFICATION_REFUSED",
"PROFILE_REPOSITORY_INVALID",
"PROFILE_REVIEW_UNSCOPED",
Expand All @@ -47,6 +48,9 @@
PROFILE_PREFLIGHT_FAILED = "PROFILE_PREFLIGHT_FAILED"
"""Raised when one or more preflight checks fail."""

PROFILE_PUBLICATION_REFUSED = "PROFILE_PUBLICATION_REFUSED"
"""Raised when no recorded Re-verification can be read for publication (nothing is written)."""

PROFILE_RATIFICATION_REFUSED = "PROFILE_RATIFICATION_REFUSED"
"""Raised when an inventory version cannot be ratified (nothing is written)."""

Expand Down
110 changes: 110 additions & 0 deletions kits/profile-dev-kit/python/beddel_profile_dev/tools/publication.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
"""Read-only access to a recorded Re-verification for publication."""

from __future__ import annotations

import hashlib
from typing import Any

from beddel.tools import beddel_tool

from beddel_profile_dev._errors import PROFILE_PUBLICATION_REFUSED, ProfileError
from beddel_profile_dev._io import real_repo_root, records_root
from beddel_profile_dev.config import load_config
from beddel_profile_dev.inventory import is_valid_id
from beddel_profile_dev.tools.report import (
_DIGEST,
REPORT_SCHEMA,
_Reader,
_report_history,
_valid_change,
)

__all__ = ["profile_read_reverification"]


def _valid_latest_report(report: dict[str, Any]) -> bool:
"""Check the fields of a stored Report that the digest re-read relies on.

Kept local: the structural boundary test keeps every module but the
decision modules free of any import of them.
"""
if "attempt" not in report:
return False
attempt = report.get("attempt")
if attempt is not None and (type(attempt) is not int or attempt < 1):
return False
reads = report.get("reads")
if not isinstance(reads, list):
return False
if any(
not isinstance(item, dict)
or set(item) != {"ref", "sha256"}
or not isinstance(item["ref"], str)
or not isinstance(item["sha256"], str)
or _DIGEST.fullmatch(item["sha256"]) is None
for item in reads
):
return False
return report.get("verdict") in {"consistent", "has pendency"}


def _refuse(reason: str) -> ProfileError:
return ProfileError(
PROFILE_PUBLICATION_REFUSED,
f"publication refused: {reason}",
{"reason": reason},
)


@beddel_tool(
name="profile_read_reverification",
description="Read the recorded Re-verification entry of the latest stored Report without writing records",
category="profile",
)
def profile_read_reverification(repo_path: str, change_id: str) -> dict[str, Any]:
"""Read the latest recorded Re-verification without changing records."""
if not is_valid_id(change_id):
raise _refuse("id.invalid")

repo = real_repo_root(repo_path)
records = records_root(repo, load_config().records_dir)
reader = _Reader(records)
if not _valid_change(reader.json(f"changes/{change_id}/change.json"), change_id):
raise _refuse("change.unrecorded")

try:
history = _report_history(reader, records, change_id)
except (ProfileError, OSError, ValueError, RecursionError):
raise _refuse("report.malformed") from None
if not history:
raise _refuse("report.absent")

ordinal, latest = history[-1]
if latest.get("schema") != REPORT_SCHEMA:
raise _refuse("reverification.not_recorded")
if not _valid_latest_report(latest):
raise _refuse("report.malformed")

for item in latest["reads"]:
try:
raw = reader.read(item["ref"])
except (ProfileError, OSError, ValueError):
raise _refuse("digest.mismatch") from None
if raw is None or hashlib.sha256(raw).hexdigest() != item["sha256"]:
raise _refuse("digest.mismatch")

reverification = latest.get("reverification")
if (
not isinstance(reverification, dict)
or reverification.get("status") != "recorded"
):
raise _refuse("reverification.not_recorded")

report_ref = f"changes/{change_id}/report/{ordinal}.json"
return {
"ok": True,
"change_id": change_id,
"report": report_ref,
"report_sha256": reader.reads[report_ref],
"reverification": reverification,
}
2 changes: 2 additions & 0 deletions kits/profile-dev-kit/tests/test_manifest.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
"profile_capture_evidence",
"profile_record_report",
"profile_read_report",
"profile_read_reverification",
"profile_declare_non_applicability",
"profile_approve_change",
"profile_record_approval_decision",
Expand Down Expand Up @@ -96,6 +97,7 @@ def test_manifest_declares_all_workflows_and_python_targets() -> None:
assert [w["name"] for w in manifest["workflows"]] == [
"verify-change",
"read-report",
"publish-reverification",
"ratify-inventory",
"declare-non-applicability",
"approve-change",
Expand Down
63 changes: 63 additions & 0 deletions kits/profile-dev-kit/tests/test_neutrality.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
"""Neutral tracked workflow and configured-term checks."""

from __future__ import annotations

import os
import subprocess
from pathlib import Path
from urllib.parse import urlsplit

import pytest
import yaml

KIT_ROOT = Path(__file__).resolve().parents[1]


def _tracked_text_files(root: Path) -> list[Path]:
output = subprocess.check_output(
["git", "-C", str(root), "ls-files", "-z"], text=False
)
return [
root / relative
for relative in output.decode().split("\0")
if relative and (root / relative).is_file()
]


def test_untracked_destination_terms_are_absent() -> None:
terms_path = os.environ.get("BEDDEL_GUARD_TERMS_FILE")
if not terms_path or not Path(terms_path).is_file():
pytest.skip("BEDDEL_GUARD_TERMS_FILE is not configured")
terms = [
line.strip()
for line in Path(terms_path).read_text().splitlines()
if line.strip()
]
if not terms:
pytest.fail("BEDDEL_GUARD_TERMS_FILE contains no terms")
root = Path(
subprocess.check_output(
["git", "-C", str(KIT_ROOT), "rev-parse", "--show-toplevel"],
text=True,
).strip()
)
hits: list[str] = []
for path in _tracked_text_files(root):
try:
text = path.read_text()
except UnicodeDecodeError:
continue
folded = text.casefold()
for index, term in enumerate(terms):
if term.casefold() in folded:
hits.append(f"{path}: listed term #{index}")
assert hits == []


def test_tracked_workflow_uses_a_non_routable_placeholder() -> None:
workflow = yaml.safe_load(
(KIT_ROOT / "workflows" / "publish-reverification.yaml").read_text()
)
endpoint = workflow["mcp_servers"]["copy_destination"]["endpoint"]
host = urlsplit(endpoint).hostname
assert host is not None and host.endswith(".invalid")
Loading
Loading