agentlinkops 0.6.13 → 0.6.16

package/skills/agentlinkops-crm/references/portable/scripts/disavow.py

@@ -0,0 +1,207 @@
+"""Offline, user-managed disavow lists. No network access or rule recommendations."""
+import datetime as dt
+import hashlib
+import ipaddress
+import json
+from pathlib import Path
+import re
+import urllib.parse
+
+# Google's help page states "2MB" without defining the byte convention.
+# Use decimal MB so every accepted export is below either common interpretation.
+MAX_BYTES = 2000000
+MAX_LINES = 100000
+MAX_URL = 2048
+
+
+class DisavowError(Exception):
+    def __init__(self, message, code="INVALID_DISAVOW"):
+        super().__init__(message)
+        self.code = code
+
+
+def stamp():
+    return dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def stable_id(prefix, parts):
+    return prefix + hashlib.sha256(json.dumps(parts, ensure_ascii=False, separators=(",", ":")).encode()).hexdigest()
+
+
+def domain(value):
+    if not isinstance(value, str):
+        raise DisavowError("Domain rule must contain a hostname")
+    value = value.strip().lower().removesuffix(".")
+    try:
+        ipaddress.ip_address(value)
+    except ValueError:
+        pass
+    else:
+        raise DisavowError("A domain rule requires a DNS hostname, not an IP address")
+    if len(value) > 253 or "." not in value or not value.isascii() or any(not re.fullmatch(r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?", label) for label in value.split(".")):
+        raise DisavowError("Domain rules require an ASCII or Punycode hostname without scheme, port, path or wildcard")
+    return value
+
+
+def url(value, property_url=False):
+    if not isinstance(value, str) or not value or len(value) > MAX_URL or any(ord(char) <= 32 or ord(char) == 127 for char in value) or "\\" in value:
+        raise DisavowError("URLs must be at most 2,048 characters without whitespace or control characters")
+    try:
+        parsed = urllib.parse.urlsplit(value)
+        if parsed.scheme not in {"http", "https"} or not parsed.hostname or parsed.username is not None or parsed.password is not None:
+            raise ValueError()
+        port = parsed.port
+        try:
+            address = ipaddress.ip_address(parsed.hostname)
+            hostname = "[" + address.compressed + "]" if address.version == 6 else address.compressed
+        except ValueError:
+            hostname = domain(parsed.hostname)
+        if port is not None:
+            hostname += ":" + str(port)
+    except (ValueError, DisavowError) as exc:
+        raise DisavowError("Use an HTTP(S) URL with an ASCII/Punycode hostname and no credentials") from exc
+    if "*" in parsed.path or "*" in parsed.query:
+        raise DisavowError("Wildcard and subpath patterns are unsupported; specify an exact page URL or a domain rule")
+    if property_url and (parsed.query or parsed.fragment):
+        raise DisavowError("Property scope must be a URL prefix without query or fragment")
+    normalized = urllib.parse.urlunsplit((parsed.scheme, hostname, parsed.path or "/", parsed.query, parsed.fragment))
+    if len(normalized) > MAX_URL:
+        raise DisavowError("Normalized URL exceeds 2,048 characters")
+    return normalized
+
+
+def rule(kind, value):
+    if kind == "domain":
+        return domain(value)
+    if kind == "url":
+        return url(value)
+    raise DisavowError("Rule kind must be domain or url")
+
+
+def source_label(value):
+    if not isinstance(value, str) or not value.strip() or len(value) > 1024 or any(ord(char) < 32 for char in value):
+        raise DisavowError("Source provenance must be a nonempty label without control characters")
+    return value.strip()
+
+
+def parse_file(path):
+    if Path(path).suffix.lower() != ".txt":
+        raise DisavowError("Disavow import requires a .txt file")
+    with Path(path).open("rb") as file:
+        raw = file.read(MAX_BYTES + 1)
+    if len(raw) > MAX_BYTES:
+        raise DisavowError("Disavow file exceeds the 2 MB limit")
+    try:
+        original = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise DisavowError("Disavow file must be UTF-8 or 7-bit ASCII") from exc
+    # Accept a UTF-8 BOM but retain the original bytes' hash and original decoded text.
+    content = original.removeprefix("\ufeff")
+    if "\x00" in content:
+        raise DisavowError("Disavow file contains NUL characters")
+    # Counting physical LF lines (including blank/comment lines) avoids treating
+    # Unicode separators inside a URL or comment as extra file lines.
+    lines = content.split("\n")
+    if lines and lines[-1] == "":
+        lines.pop()
+    if len(lines) > MAX_LINES:
+        raise DisavowError("Disavow file exceeds 100,000 lines including comments and blanks")
+    entries, comments = [], []
+    for number, original_line in enumerate(lines, 1):
+        line = original_line.rstrip("\r").strip()
+        if not line:
+            continue
+        if line.startswith("#"):
+            comments.append({"line": number, "text": line[1:].lstrip()})
+            continue
+        kind, value = ("domain", line[7:]) if line.startswith("domain:") else ("url", line)
+        try:
+            normalized = rule(kind, value)
+        except DisavowError as exc:
+            raise DisavowError(f"Line {number}: {exc}") from exc
+        entries.append({"kind": kind, "value": normalized, "line": number, "original": original_line.rstrip("\r"), "comments": comments})
+        comments = []
+    return original, hashlib.sha256(raw).hexdigest(), entries, len(lines)
+
+
+def import_rules(connection, path, property_url, source):
+    property_url, source = url(property_url, True), source_label(source)
+    original, digest, entries, line_count = parse_file(path)
+    source_id = stable_id("dsrc_", [property_url, source, digest, "txt"])
+    added, existing, recorded = 0, 0, stamp()
+    connection.execute("BEGIN IMMEDIATE")
+    try:
+        connection.execute("INSERT OR IGNORE INTO disavow_sources VALUES (?,?,?,?,?,?,?)", (source_id, property_url, source, digest, "txt", original, recorded))
+        for entry in entries:
+            rule_id = stable_id("drule_", [property_url, entry["kind"], entry["value"]])
+            inserted = connection.execute("INSERT OR IGNORE INTO disavow_rules(id,property_url,kind,value,created_at,updated_at) VALUES (?,?,?,?,?,?)", (rule_id, property_url, entry["kind"], entry["value"], recorded, recorded)).rowcount
+            added += inserted
+            existing += 1 - inserted
+            # An import never overwrites local notes or reactivates a rule the user disabled.
+            connection.execute("INSERT OR IGNORE INTO disavow_provenance VALUES (?,?,?,?,?,?)", (rule_id, source_id, entry["line"], entry["original"], json.dumps(entry["comments"], ensure_ascii=False), recorded))
+        connection.execute("COMMIT")
+    except Exception:
+        connection.execute("ROLLBACK")
+        raise
+    return {"property_url": property_url, "source_id": source_id, "rules_added": added, "existing_rule_lines": existing, "lines": line_count, "mode": "merge", "uploaded": False}
+
+
+def upsert_rule(connection, record, property_url, source):
+    property_url, source = url(property_url, True), source_label(source)
+    if not isinstance(record, dict) or record.keys() - {"kind", "value", "active", "notes"}:
+        raise DisavowError("Rule JSON accepts kind, value, active and notes")
+    kind = record.get("kind")
+    value = rule(kind, record.get("value"))
+    if "active" in record and type(record["active"]) is not bool:
+        raise DisavowError("active must be a JSON boolean")
+    if "notes" in record and not isinstance(record["notes"], str):
+        raise DisavowError("notes must be a string")
+    rule_id = stable_id("drule_", [property_url, kind, value])
+    raw = json.dumps(record, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    digest = hashlib.sha256(raw.encode()).hexdigest()
+    source_id = stable_id("dsrc_", [property_url, source, digest, "manual"])
+    recorded = stamp()
+    connection.execute("BEGIN IMMEDIATE")
+    try:
+        existing = connection.execute("SELECT active,notes FROM disavow_rules WHERE id=?", (rule_id,)).fetchone()
+        active = int(record.get("active", bool(existing[0]) if existing else True))
+        notes = record.get("notes", existing[1] if existing else "")
+        connection.execute("INSERT INTO disavow_rules VALUES (?,?,?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET active=excluded.active,notes=excluded.notes,updated_at=excluded.updated_at", (rule_id, property_url, kind, value, active, notes, recorded, recorded))
+        connection.execute("INSERT OR IGNORE INTO disavow_sources VALUES (?,?,?,?,?,?,?)", (source_id, property_url, source, digest, "manual", raw, recorded))
+        connection.execute("INSERT OR IGNORE INTO disavow_provenance VALUES (?,?,?,?,?,?)", (rule_id, source_id, 0, raw, "[]", recorded))
+        connection.execute("COMMIT")
+    except Exception:
+        connection.execute("ROLLBACK")
+        raise
+    return {"id": rule_id, "property_url": property_url, "kind": kind, "value": value, "active": bool(active), "notes": notes, "source_id": source_id}
+
+
+def list_rules(connection, property_url, active_only=False):
+    property_url = url(property_url, True)
+    result = []
+    for row in connection.execute("SELECT * FROM disavow_rules WHERE property_url=?" + (" AND active=1" if active_only else "") + " ORDER BY kind,value", (property_url,)):
+        item = dict(row)
+        item["active"] = bool(item["active"])
+        item["provenance"] = []
+        for source in connection.execute("SELECT s.id AS source_id,s.source_label,s.source_sha256,s.format,p.line_number,p.line_text,p.comments_json,p.recorded_at FROM disavow_provenance p JOIN disavow_sources s ON s.id=p.source_id WHERE p.rule_id=? ORDER BY p.recorded_at,s.id,p.line_number", (item["id"],)):
+            entry = dict(source)
+            entry["comments"] = json.loads(entry.pop("comments_json"))
+            item["provenance"].append(entry)
+        result.append(item)
+    return result
+
+
+def export_rules(connection, property_url):
+    property_url = url(property_url, True)
+    # No timestamps or private notes: the same active rule set produces identical bytes.
+    lines = ["# AgentLinkOps user-managed disavow rules", "# Property: " + property_url]
+    for kind, value in connection.execute("SELECT kind,value FROM disavow_rules WHERE property_url=? AND active=1 ORDER BY kind,value", (property_url,)):
+        lines.append("domain:" + value if kind == "domain" else value)
+    text = "\n".join(lines) + "\n"
+    if len(lines) > MAX_LINES or len(text.encode("utf-8")) > MAX_BYTES:
+        raise DisavowError("Export exceeds Google's .txt line or byte limits; review the list before exporting")
+    return text, {"property_url": property_url, "active_rules": len(lines) - 2, "format": "txt", "uploaded": False}
+
+
+def snapshot(connection):
+    return {"rules": [dict(row) for row in connection.execute("SELECT * FROM disavow_rules ORDER BY property_url,kind,value")], "sources": [dict(row) for row in connection.execute("SELECT * FROM disavow_sources ORDER BY id")], "provenance": [dict(row) for row in connection.execute("SELECT * FROM disavow_provenance ORDER BY rule_id,source_id,line_number")]}

package/skills/agentlinkops-crm/references/portable/scripts/migrations/001_crm.sql

@@ -0,0 +1,45 @@
+CREATE TABLE crm_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+CREATE TABLE products (
+  id TEXT PRIMARY KEY, name TEXT NOT NULL, url TEXT NOT NULL,
+  audience TEXT NOT NULL DEFAULT '', description TEXT NOT NULL DEFAULT '',
+  target_pages TEXT NOT NULL DEFAULT '[]', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE TABLE campaigns (
+  id TEXT PRIMARY KEY, product_id TEXT REFERENCES products(id), name TEXT NOT NULL,
+  type TEXT NOT NULL, template_version INTEGER NOT NULL DEFAULT 1,
+  status TEXT NOT NULL DEFAULT 'draft', goal TEXT NOT NULL DEFAULT '',
+  target_url TEXT NOT NULL DEFAULT '', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE TABLE contacts (
+  id TEXT PRIMARY KEY, publisher_url TEXT NOT NULL, name TEXT NOT NULL DEFAULT '',
+  email TEXT NOT NULL DEFAULT '', contact_url TEXT NOT NULL DEFAULT '',
+  source_url TEXT NOT NULL DEFAULT '', observed_at TEXT NOT NULL DEFAULT '',
+  confidence TEXT NOT NULL DEFAULT 'unverified', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE TABLE opportunities (
+  id TEXT PRIMARY KEY, campaign_id TEXT REFERENCES campaigns(id),
+  contact_id TEXT REFERENCES contacts(id), source_url TEXT NOT NULL, target_url TEXT NOT NULL,
+  type TEXT NOT NULL DEFAULT 'custom', status TEXT NOT NULL DEFAULT 'candidate',
+  evidence TEXT NOT NULL DEFAULT '{}', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE TABLE activities (
+  id TEXT PRIMARY KEY, opportunity_id TEXT REFERENCES opportunities(id),
+  contact_id TEXT REFERENCES contacts(id), campaign_id TEXT REFERENCES campaigns(id),
+  channel TEXT NOT NULL DEFAULT 'email', kind TEXT NOT NULL,
+  external_message_id TEXT NOT NULL DEFAULT '', occurred_at TEXT NOT NULL,
+  outcome TEXT NOT NULL DEFAULT '', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE TABLE placements (
+  id TEXT PRIMARY KEY, opportunity_id TEXT REFERENCES opportunities(id),
+  project_id TEXT, watch_id TEXT UNIQUE, source_url TEXT NOT NULL, target_url TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending', notes TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE INDEX campaigns_product ON campaigns(product_id);
+CREATE INDEX opportunities_campaign ON opportunities(campaign_id);
+CREATE INDEX activities_opportunity ON activities(opportunity_id, occurred_at);

package/skills/agentlinkops-crm/references/portable/scripts/migrations/002_cloud_events.sql

@@ -0,0 +1,13 @@
+ALTER TABLE placements ADD COLUMN cloud_state TEXT NOT NULL DEFAULT '{}';
+ALTER TABLE placements ADD COLUMN cloud_observed_at TEXT;
+ALTER TABLE placements ADD COLUMN cloud_event_id TEXT;
+CREATE TABLE cloud_events (
+  id TEXT PRIMARY KEY, cursor TEXT NOT NULL UNIQUE, type TEXT NOT NULL,
+  project_id TEXT, watch_id TEXT, created_at TEXT NOT NULL,
+  payload TEXT NOT NULL, payload_hash TEXT NOT NULL, applied_at TEXT NOT NULL
+);
+CREATE TABLE sync_state (
+  singleton INTEGER PRIMARY KEY CHECK(singleton = 1),
+  endpoint TEXT, cursor TEXT, updated_at TEXT NOT NULL
+);
+INSERT INTO sync_state(singleton, updated_at) VALUES(1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));

package/skills/agentlinkops-crm/references/portable/scripts/migrations/003_disavow.sql

@@ -0,0 +1,20 @@
+CREATE TABLE disavow_rules (
+  id TEXT PRIMARY KEY, property_url TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK(kind IN ('domain','url')), value TEXT NOT NULL,
+  active INTEGER NOT NULL DEFAULT 1 CHECK(active IN (0,1)),
+  notes TEXT NOT NULL DEFAULT '', created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+  UNIQUE(property_url,kind,value)
+);
+CREATE TABLE disavow_sources (
+  id TEXT PRIMARY KEY, property_url TEXT NOT NULL, source_label TEXT NOT NULL,
+  source_sha256 TEXT NOT NULL, format TEXT NOT NULL CHECK(format IN ('txt','manual')),
+  raw_text TEXT NOT NULL, created_at TEXT NOT NULL
+);
+CREATE TABLE disavow_provenance (
+  rule_id TEXT NOT NULL REFERENCES disavow_rules(id),
+  source_id TEXT NOT NULL REFERENCES disavow_sources(id),
+  line_number INTEGER NOT NULL, line_text TEXT NOT NULL,
+  comments_json TEXT NOT NULL DEFAULT '[]', recorded_at TEXT NOT NULL,
+  PRIMARY KEY(rule_id,source_id,line_number)
+);
+CREATE INDEX disavow_property_rules ON disavow_rules(property_url,active,kind,value);

package/skills/agentlinkops-crm/references/portable/scripts/migrations/004_placement_costs.sql

@@ -0,0 +1,2 @@
+ALTER TABLE placements ADD COLUMN cost_amount TEXT;
+ALTER TABLE placements ADD COLUMN cost_currency TEXT;

package/skills/agentlinkops-crm/references/portable/scripts/outreach-crm-draft.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Save/read back an explicitly mapped draft in a customer-selected local Outreach CRM.
+No network, send, sequence activation, or contact/authority-state writes.
+"""
+import argparse
+import hashlib
+import importlib.util
+import json
+from pathlib import Path
+import re
+from urllib.parse import urlsplit
+
+spec = importlib.util.spec_from_file_location('portable_handoff', Path(__file__).with_name('portable-handoff.py'))
+portable = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(portable)
+
+
+def text(value, label):
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(label + ' must be explicit')
+    return value
+
+
+def host(value):
+    parsed = urlsplit(text(value, 'site'))
+    if parsed.scheme not in ('https', 'http') or not parsed.hostname or parsed.username or parsed.password:
+        raise ValueError('site must be an explicit URL without credentials')
+    return parsed.hostname.lower()
+
+
+def prepare(root, request, body):
+    fields = {'version', 'crm_project', 'workspace_id', 'project_id', 'site', 'operation_id',
+              'original_request', 'local_id', 'external_id', 'observation', 'reply',
+              'suppression', 'subject', 'body_sha256'}
+    if not isinstance(request, dict) or set(request) != fields or type(request['version']) is not int or request['version'] != 1:
+        raise ValueError('explicit version 1 draft request required; see local CRM handoff reference')
+    for field in fields - {'version', 'original_request'}:
+        text(request[field], field)
+    project = request['crm_project']
+    if not re.fullmatch(r'[a-z0-9][a-z0-9_-]*', project):
+        raise ValueError('crm_project must be one project directory name')
+    root = Path(root).resolve(strict=True)
+    project_dir = root / 'projects' / project
+    # Refuse symlink redirection in destination directories, including an existing
+    # operation directory. This is a cooperating local writer, not an OS sandbox.
+    for path in (root / 'projects', project_dir, project_dir / 'config.json', project_dir / 'drafts'):
+        if path.is_symlink():
+            raise ValueError('destination symlink refused: ' + str(path))
+    config = json.loads((project_dir / 'config.json').read_text(encoding='utf-8'))
+    if not isinstance(config, dict) or config.get('project') != project or host(config.get('site')) != host(request['site']):
+        raise ValueError('CRM config identity/site mismatch; preserve original mapping')
+    if not (project_dir / 'drafts').is_dir():
+        raise ValueError('selected CRM drafts directory missing; initialize that project first')
+    original = request['original_request']
+    if not isinstance(original, dict) or set(original) != {'destination', 'workspace_id', 'project_id', 'command', 'arguments', 'idempotency_key'}:
+        raise ValueError('complete original non-secret request tuple required')
+    for field in ('destination', 'workspace_id', 'project_id', 'command', 'idempotency_key'):
+        text(original[field], 'original_request.' + field)
+    if not isinstance(original['arguments'], dict):
+        raise ValueError('original request arguments must be an object')
+    if any(original[field] != request[field] for field in ('workspace_id', 'project_id')):
+        raise ValueError('original request scope mismatch; preserve original mapping')
+    if request['observation'] not in ('unknown', 'present', 'provisional_loss', 'confirmed_loss'):
+        raise ValueError('explicit supported observation required')
+    if request['reply'] not in ('unknown', 'none', 'replied') or request['suppression'] not in ('unknown', 'clear', 'suppressed'):
+        raise ValueError('explicit reply/suppression observation required')
+    if '\n' in request['subject'] or '\r' in request['subject']:
+        raise ValueError('subject must be one line')
+    body.decode('utf-8')
+    if not body or hashlib.sha256(body).hexdigest() != request['body_sha256']:
+        raise ValueError('body bytes do not match the original draft hash')
+    identity = {field: request[field] for field in ('crm_project', 'workspace_id', 'project_id', 'operation_id', 'local_id', 'external_id')}
+    directory = project_dir / 'drafts' / ('agentlinkops-' + portable.digest(identity))
+    if directory.is_symlink():
+        raise ValueError('destination operation symlink refused')
+    manifest = {'version': 1, 'destination': 'local-outreach-crm-drafts', 'request': request,
+                'body_file': 'body.txt', 'send_eligible': False, 'messages_sent': 0,
+                'native_vendor_acceptance': False, 'hosted_scope_verification': 'customer_supplied_unverified'}
+    return directory, (portable.canonical(manifest) + '\n').encode('utf-8')
+
+
+def save(root, request, body, readback=False):
+    directory, manifest = prepare(root, request, body)
+    artifacts = [(directory / 'body.txt', body), (directory / 'manifest.json', manifest)]
+    if readback and not directory.is_dir():
+        raise ValueError('draft readback missing; resume the original save')
+    if not readback:
+        directory.mkdir(exist_ok=True)
+    with portable._publication_lock(directory / 'draft-transaction'):
+        for path, expected in artifacts:
+            if path.is_symlink() or (path.exists() and (not path.is_file() or path.read_bytes() != expected)):
+                raise ValueError('saved draft differs; retain original operation and inspect ' + str(path))
+            if readback and not path.is_file():
+                raise ValueError('draft readback incomplete; resume the original save')
+        outcomes = [] if readback else [portable._publish_bytes(path, expected) for path, expected in artifacts]
+        if any(path.read_bytes() != expected for path, expected in artifacts):
+            raise ValueError('draft readback mismatch; preserve original operation')
+    return {'operation_id': request['operation_id'], 'crm_project': request['crm_project'],
+            'local_id': request['local_id'], 'external_id': request['external_id'],
+            'directory': str(directory), 'body_sha256': request['body_sha256'],
+            'manifest_sha256': hashlib.sha256(manifest).hexdigest(),
+            'outcome': 'saved_and_read_back' if 'saved_and_read_back' in outcomes else 'identical_readback',
+            'messages_sent': 0, 'send_eligible': False, 'native_vendor_acceptance': False}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--crm-root', required=True)
+    parser.add_argument('--request', required=True)
+    parser.add_argument('--body-file', required=True)
+    parser.add_argument('--readback', action='store_true')
+    args = parser.parse_args()
+    request = json.loads(Path(args.request).read_text(encoding='utf-8'))
+    print(portable.canonical(save(args.crm_root, request, Path(args.body_file).read_bytes(), args.readback)))
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except (ValueError, OSError, KeyError, TypeError) as error:
+        raise SystemExit('local CRM draft refused: ' + str(error))

package/skills/agentlinkops-crm/references/portable/scripts/portable-handoff.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""Local draft-only handoff from a frozen report and explicit external-ID mapping.
+No network, mailbox, sender or mutation of the input ledger/report. No send action.
+"""
+import argparse
+from contextlib import contextmanager
+import errno
+import hashlib
+import json
+import os
+from pathlib import Path
+import tempfile
+import stat
+import time
+from urllib.parse import urlsplit
+
+
+def canonical(value):
+    return json.dumps(value, sort_keys=True, separators=(',', ':'), ensure_ascii=False)
+
+
+def digest(value):
+    return hashlib.sha256(canonical(value).encode()).hexdigest()
+
+
+def prepare(report, mapping):
+    if not isinstance(report, dict) or not isinstance(mapping, dict) or type(report.get('v')) is not int or report['v'] not in (2, 3):
+        raise ValueError('supported frozen report v2 or v3 and mapping objects required')
+    if set(mapping) != {'version', 'workspace_id', 'project_id', 'site', 'destination', 'records', 'source_report_sha256'} or type(mapping['version']) is not int or mapping['version'] != 1:
+        raise ValueError('explicit versioned workspace/project/site/destination mapping required')
+    if any(not isinstance(mapping[k], str) or not mapping[k] or len(mapping[k]) > 2048 for k in ('workspace_id', 'project_id', 'site', 'destination')):
+        raise ValueError('mapping identity missing')
+    if mapping['destination'] != 'portable-file':
+        raise ValueError('native vendor adapter unsupported; use portable-file')
+    if mapping['source_report_sha256'] != digest(report):
+        raise ValueError('mapping belongs to another frozen report; scope refused')
+    site = urlsplit(mapping['site'])
+    if site.scheme not in ('http', 'https') or not site.hostname or site.username or site.password:
+        raise ValueError('explicit site URL required')
+    if not isinstance(report.get('rows'), list) or not isinstance(mapping['records'], dict):
+        raise ValueError('frozen report entries and explicit record mappings required')
+    rows, seen, external = [], set(), set()
+    for entry in report['rows']:
+        if not isinstance(entry, dict) or not {'id','source','target','state','reason','checked_at','evidence'}.issubset(entry):
+            raise ValueError('incomplete frozen observation row')
+        for field in ('source', 'target'):
+            url = urlsplit(entry[field])
+            if url.scheme not in ('http', 'https') or not url.hostname or url.username or url.password:
+                raise ValueError('public source and target URLs without credentials required')
+        local_id = entry.get('id')
+        if not isinstance(local_id, str) or not local_id or local_id in seen:
+            raise ValueError('missing or duplicate local identity')
+        if urlsplit(entry.get('target') or '').hostname != site.hostname:
+            raise ValueError('target belongs to another site; scope refused')
+        seen.add(local_id)
+        record = mapping['records'].get(local_id)
+        if not record or set(record) != {'external_id', 'reply', 'suppression'}:
+            raise ValueError('explicit external identity/reply/suppression required for every row')
+        if not isinstance(record['external_id'], str) or not record['external_id'] or record['external_id'] in external:
+            raise ValueError('missing or duplicate external identity')
+        external.add(record['external_id'])
+        if record['reply'] not in ('unknown', 'none', 'replied') or record['suppression'] not in ('unknown', 'suppressed', 'clear'):
+            raise ValueError('unknown/replied/suppressed facts must remain explicit')
+        # Keep the original observation payload and dates. Unknown never becomes lost.
+        row = {'local_id': local_id, 'external_id': record['external_id'],
+                     'source': entry.get('source'), 'target': entry.get('target'),
+                     'state': entry['state'], 'reason': entry['reason'], 'checked_at': entry['checked_at'], 'evidence': entry['evidence'],
+                     'checked_by': entry.get('checked_by'), 'occurrences': entry.get('occurrences'),
+                     'reply': record['reply'], 'suppression': record['suppression'],
+                     'send_eligible': False}
+        if report['v'] == 3:
+            # Activity and retained receipts are different facts. Preserve both;
+            # a later unknown attempt must not disappear behind an older receipt.
+            activity = entry.get('activity')
+            activity_fields = {'available', 'identity_status', 'latest_attempt',
+                               'last_successful_observation', 'last_link_verification', 'first_present'}
+            if entry.get('current_state') not in ('present', 'unknown', 'source_unavailable',
+                                                'suspected_missing', 'confirmed_missing', 'unchecked') \
+                    or type(entry.get('uncertain')) is not bool or not isinstance(activity, dict) \
+                    or not activity_fields.issubset(activity):
+                raise ValueError('incomplete frozen report v3 activity row')
+            row.update(current_state=entry['current_state'], uncertain=entry['uncertain'], activity=activity)
+        rows.append(row)
+    if set(mapping['records']) != seen:
+        raise ValueError('mapping contains records outside this frozen report')
+    payload = {'version': 1, 'mode': 'draft_only', 'workspace_id': mapping['workspace_id'],
+               'project_id': mapping['project_id'], 'site': mapping['site'], 'destination': mapping['destination'],
+               'scope_verification': 'customer_supplied_mapping_unverified_hosted',
+               'source_report_sha256': digest(report), 'mapping_sha256': digest(mapping),
+               'rows': sorted(rows, key=lambda row: row['local_id'])}
+    return {**payload, 'operation_id': 'portable_' + digest(payload), 'messages_sent': 0,
+            'destination_outcome': 'not_attempted', 'native_vendor_acceptance': False}
+
+
+@contextmanager
+def _publication_lock(output):
+    # Unsupported filesystems cannot publish by exclusive link. Serialize this
+    # helper's writers in a host-local kernel lock; never infer lock ownership
+    # from the existence or age of the cache file.
+    try:
+        import fcntl
+    except ImportError as error:
+        raise ValueError('filesystem lacks exclusive publication and native writer locking; preserve the checkpoint and use a supported local filesystem') from error
+    root = Path('/tmp') / ('agentlinkops-handoff-locks-' + str(os.getuid()))
+    root.mkdir(mode=0o700, exist_ok=True)
+    info = root.lstat()
+    if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
+        raise ValueError('publication lock directory is not private; preserve the checkpoint')
+    parent = output.parent.resolve()
+    parent_info = parent.stat()
+    identity = canonical([parent_info.st_dev, parent_info.st_ino, output.name.casefold()])
+    lock_path = root / (hashlib.sha256(identity.encode('utf-8')).hexdigest() + '.lock')
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600)
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
+            raise ValueError('publication lock file is not private; preserve the checkpoint')
+        deadline = time.monotonic() + 5
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise ValueError('draft publication is busy; preserve the original operation and read back after its writer finishes')
+                time.sleep(0.02)
+        try:
+            yield
+        finally:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+    finally:
+        os.close(fd)
+
+
+def _publish_bytes(output, content):
+    output = Path(output)
+    if output.exists():
+        if output.read_bytes() != content:
+            raise ValueError('existing handoff differs; preserve checkpoint and choose a new output')
+        return 'identical_readback'
+    output.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix='.handoff-', dir=output.parent)
+    try:
+        with os.fdopen(fd, 'wb') as f:
+            f.write(content); f.flush(); os.fsync(f.fileno())
+        try:
+            os.link(temporary, output)
+        except FileExistsError:
+            if output.read_bytes() != content:
+                raise ValueError('concurrent handoff differs; preserve checkpoint')
+            return 'identical_readback'
+        except OSError as error:
+            if error.errno not in {errno.ENOTSUP, errno.EOPNOTSUPP, errno.ENOSYS}:
+                raise
+            # ExFAT has neither hard links nor exclusive rename. All fallback
+            # writers take the same kernel lock and re-read before publication.
+            # This protects cooperating helper writers, not arbitrary external
+            # applications writing the same filename outside this protocol.
+            with _publication_lock(output):
+                if output.exists():
+                    if output.read_bytes() != content:
+                        raise ValueError('concurrent handoff differs; preserve checkpoint')
+                    return 'identical_readback'
+                os.rename(temporary, output)
+                if output.read_bytes() != content:
+                    raise ValueError('artifact readback mismatch; preserve operation identity')
+        if output.read_bytes() != content:
+            raise ValueError('artifact readback mismatch; preserve operation identity')
+    finally:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass  # A successful rename consumed only this writer's temporary.
+    return 'saved_and_read_back'
+
+
+def save(bundle, output):
+    return _publish_bytes(output, (canonical(bundle) + '\n').encode('utf-8'))
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--report', required=True)
+    parser.add_argument('--mapping', required=True)
+    parser.add_argument('--out', required=True)
+    args = parser.parse_args()
+    bundle = prepare(json.loads(Path(args.report).read_text(encoding='utf-8')), json.loads(Path(args.mapping).read_text(encoding='utf-8')))
+    receipt = save(bundle, args.out)
+    print(canonical({'operation_id': bundle['operation_id'], 'artifact': receipt, 'rows': len(bundle['rows']),
+                     'messages_sent': 0, 'destination_outcome': 'not_attempted'}))
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except (ValueError, OSError, KeyError, TypeError) as error:
+        raise SystemExit('portable handoff refused: ' + str(error))