forge-autonomy 2.7.39__tar.gz → 2.12.2__tar.gz

{forge_autonomy-2.7.39/forge_autonomy.egg-info → forge_autonomy-2.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forge-autonomy
-Version: 2.7.39
+Version: 2.12.2
 Summary: Forge mission planning, producer contracts, and evidence interpretation runtime.
 Author: Forge maintainers
 License-Expression: Apache-2.0
@@ -11,9 +11,12 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.14
 Description-Content-Type: text/markdown
+Provides-Extra: validation
+Requires-Dist: coverage<8,>=7; extra == "validation"
+Requires-Dist: jsonschema<5,>=4; extra == "validation"
 
 # Forge
 

{forge_autonomy-2.7.39 → forge_autonomy-2.12.2}/forge/__main__.py

@@ -219,6 +219,36 @@ def main(argv: list[str] | None = None) -> int:
         if name in {"run", "reopen"}:
             command.add_argument("--poll-seconds", type=float, default=1.0)
             command.add_argument("--maximum-wait-seconds", type=float, default=3600.0)
+    progression_policy = mission_commands.add_parser(
+        "progression-policy", help="bind one versioned Mission progression policy")
+    progression_policy.add_argument("--mission-id", required=True)
+    progression_policy.add_argument("--input", required=True)
+    progression_decide = mission_commands.add_parser(
+        "progression-decide", help="record one exact post-Action progression decision")
+    progression_decide.add_argument("--mission-id", required=True)
+    progression_decide.add_argument("--input", required=True)
+    progression_status = mission_commands.add_parser(
+        "progression-status", help="read the current post-Action progression fence")
+    progression_status.add_argument("--mission-id", required=True)
+    final_acceptance = mission_commands.add_parser(
+        "accept-final-completion", help="record Business acceptance of proven Mission completion")
+    final_acceptance.add_argument("--mission-id", required=True)
+    final_acceptance.add_argument("--input", required=True)
+    installation = subparsers.add_parser("installation-peer", help="manage project-independent EP installation connectivity")
+    installation_commands = installation.add_subparsers(dest="installation_peer_command", required=True)
+    configure_installation = installation_commands.add_parser("configure")
+    for flag in ("operation-id", "binding-id", "endpoint", "expected-instance-id", "consumer-id", "credential-reference"):
+        configure_installation.add_argument("--"+flag, required=True)
+    configure_installation.add_argument("--allow-loopback-http",action="store_true")
+    configure_installation.add_argument("--timeout-seconds",type=float,default=10.0)
+    installation_commands.add_parser("show")
+    installation_commands.add_parser("preflight")
+    detach_installation = installation_commands.add_parser("detach")
+    detach_installation.add_argument("--operation-id", required=True)
+    detach_installation.add_argument("--expected-binding-id", required=True)
+    detach_installation.add_argument("--expected-configuration-revision", type=int, required=True)
+    installation_detach_status = installation_commands.add_parser("detach-status")
+    installation_detach_status.add_argument("--operation-id", required=True)
     execution_host = subparsers.add_parser("execution-host", help="manage the selected Execution Host peer")
     execution_host_commands = execution_host.add_subparsers(dest="execution_host_command", required=True)
     configure = execution_host_commands.add_parser("configure", help="persist one explicit EP peer binding")
@@ -427,6 +457,22 @@ def main(argv: list[str] | None = None) -> int:
                 result = mission_cli.admit(args.data_root, args.input)
             elif command == "status":
                 result = mission_cli.status(args.data_root, args.mission_id)
+            elif command == "progression-policy":
+                if args.data_root is None:
+                    raise ValueError("--data-root is required for progression policy")
+                result = mission_cli.progression_policy(args.data_root, args.mission_id, args.input)
+            elif command == "progression-status":
+                if args.data_root is None:
+                    raise ValueError("--data-root is required for progression status")
+                result = mission_cli.progression_status(args.data_root, args.mission_id)
+            elif command == "progression-decide":
+                if args.data_root is None:
+                    raise ValueError("--data-root is required for progression decision")
+                result = mission_cli.progression_decide(args.data_root, args.mission_id, args.input)
+            elif command == "accept-final-completion":
+                if args.data_root is None:
+                    raise ValueError("--data-root is required for final Business acceptance")
+                result = mission_cli.accept_final_completion(args.data_root, args.mission_id, args.input)
             elif command == "stop":
                 result = mission_cli.stop(args.data_root, args.mission_id)
             else:
@@ -511,6 +557,25 @@ def main(argv: list[str] | None = None) -> int:
                 }
             print(json.dumps(envelope, sort_keys=True))
             return 1
+    elif args.command == "installation-peer":
+        from .installation_pairing import InstallationPairingService, InstallationPairingError
+        try:
+            service = InstallationPairingService(args.data_root)
+            if args.installation_peer_command == "configure":
+                result = service.configure(operation_id=args.operation_id,binding_id=args.binding_id,
+                    endpoint=args.endpoint,ep_instance_id=args.expected_instance_id,consumer_id=args.consumer_id,
+                    credential_reference=args.credential_reference,allow_loopback_http=args.allow_loopback_http,
+                    timeout_seconds=args.timeout_seconds)
+            elif args.installation_peer_command == "detach":
+                result = service.detach(operation_id=args.operation_id,
+                    expected_binding_id=args.expected_binding_id,
+                    expected_configuration_revision=args.expected_configuration_revision)
+            elif args.installation_peer_command == "detach-status": result = service.detach_status(args.operation_id)
+            elif args.installation_peer_command == "show": result = service.show()
+            else: result = service.preflight()
+            print(json.dumps(result,sort_keys=True))
+        except (RuntimeError,PermissionError,ValueError,sqlite3.Error,OSError):
+            return _failure("installation-peer",InstallationPairingError("INSTALLATION_PAIRING_REJECTED"))
     elif args.command == "execution-host":
         try:
             if args.execution_host_command == "credential-access":

forge_autonomy-2.12.2/forge/action_frontier.py

@@ -0,0 +1,140 @@
+"""Bounded, read-only logical Action frontier for an installed Mission.
+
+This projection never decides host admission. A stored Action has no durable
+per-Action target or predecessor evidence predicate in the serial schema, so
+the result must not be interpreted as a dispatchable parallel workset.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+import re
+from typing import Any
+
+
+FRONTIER_CONTRACT_VERSION = "parallel-action-frontier/v2"
+MAX_FRONTIER_ACTIONS = 256
+_STATUSES = frozenset({"READY", "ACTIVE", "WAITING_FOR_RESULT", "COMPLETE", "BLOCKED", "FAILED"})
+_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z")
+_BINDING_RESOLUTIONS = frozenset({"MATCHED_SELECTED_BINDING", "MISMATCH", "UNCONFIGURED"})
+
+
+class ActionFrontierError(ValueError):
+    """The installed Action graph cannot be safely represented as a DAG."""
+
+
+def project_action_frontier(actions: Sequence[Mapping[str, Any]], *, mission_revision: int,
+                            pinned_slots: Mapping[str, Any] | None = None) -> dict[str, Any]:
+    """Return a deterministic logical frontier without claiming execution eligibility."""
+    if len(actions) > MAX_FRONTIER_ACTIONS:
+        raise ActionFrontierError("Mission Action graph exceeds the bounded read limit")
+    if not isinstance(mission_revision, int) or isinstance(mission_revision, bool) or mission_revision < 1:
+        raise ActionFrontierError("Mission graph revision is invalid")
+    nodes: dict[str, dict[str, Any]] = {}
+    orders: set[int] = set()
+    for action in actions:
+        if not isinstance(action, Mapping):
+            raise ActionFrontierError("Mission Action record is invalid")
+        action_id = action.get("id")
+        order = action.get("order")
+        status = action.get("status")
+        edges = action.get("dependencies", ())
+        if (not isinstance(action_id, str) or not action_id or action_id in nodes
+                or not isinstance(order, int) or isinstance(order, bool) or order < 1 or order in orders
+                or not isinstance(status, str) or status not in _STATUSES
+                or not isinstance(edges, (list, tuple))
+                or any(not isinstance(edge, str) or not edge for edge in edges)
+                or len(edges) != len(set(edges))):
+            raise ActionFrontierError("Mission Action identity, order, status or edges are invalid")
+        orders.add(order)
+        nodes[action_id] = {"action_id": action_id, "order": order, "status": status,
+                            "dependencies": tuple(edges)}
+    for node in nodes.values():
+        if node["action_id"] in node["dependencies"] or any(
+            edge not in nodes for edge in node["dependencies"]
+        ):
+            raise ActionFrontierError("Mission Action graph has an unresolved edge")
+    active: set[str] = set()
+    complete: set[str] = set()
+
+    def visit(action_id: str) -> None:
+        if action_id in active:
+            raise ActionFrontierError("Mission Action graph has a cycle")
+        if action_id in complete:
+            return
+        active.add(action_id)
+        for predecessor in nodes[action_id]["dependencies"]:
+            visit(predecessor)
+        active.remove(action_id)
+        complete.add(action_id)
+
+    for action_id in nodes:
+        visit(action_id)
+    target_slots: dict[str, Mapping[str, Any]] = {}
+    source_slot_digest = None
+    if pinned_slots is not None:
+        if not isinstance(pinned_slots, Mapping):
+            raise ActionFrontierError("Mission Action target slots are invalid")
+        entries = pinned_slots.get("actions")
+        digest = pinned_slots.get("document_digest")
+        if (pinned_slots.get("freshness") != "CURRENT"
+                or not isinstance(pinned_slots.get("mission_revision"), int)
+                or isinstance(pinned_slots["mission_revision"], bool)
+                or pinned_slots["mission_revision"] != mission_revision
+                or pinned_slots.get("target_verification") != "UNVERIFIED"
+                or pinned_slots.get("dispatch_authorized") is not False
+                or not isinstance(digest, str) or _DIGEST.fullmatch(digest) is None
+                or not isinstance(entries, list) or len(entries) != len(nodes)):
+            raise ActionFrontierError("Mission Action target slots are not current and pinned")
+        for entry in entries:
+            if not isinstance(entry, Mapping):
+                raise ActionFrontierError("Mission Action target slot is invalid")
+            action_id = entry.get("action_id")
+            target = entry.get("target")
+            if (not isinstance(action_id, str) or action_id not in nodes or action_id in target_slots
+                    or not isinstance(target, Mapping)
+                    or not isinstance(target.get("repository_id"), str)
+                    or not target["repository_id"]
+                    or entry.get("baseline_verification") != "UNVERIFIED"
+                    or not isinstance(entry.get("selected_binding_resolution"), str)
+                    or entry["selected_binding_resolution"] not in _BINDING_RESOLUTIONS):
+                raise ActionFrontierError("Mission Action target slot is invalid")
+            target_slots[action_id] = entry
+        source_slot_digest = digest
+    ordered = sorted(nodes.values(), key=lambda node: (node["order"], node["action_id"]))
+    frontier: list[str] = []
+    projected: list[dict[str, Any]] = []
+    for node in ordered:
+        dependencies = node["dependencies"]
+        if node["status"] != "READY":
+            logical_state = node["status"]
+        elif any(nodes[edge]["status"] in {"FAILED", "BLOCKED"} for edge in dependencies):
+            logical_state = "BLOCKED_BY_PREDECESSOR"
+        elif any(nodes[edge]["status"] != "COMPLETE" for edge in dependencies):
+            logical_state = "WAITING_FOR_PREDECESSOR"
+        elif dependencies:
+            # Serial storage does not bind a verified predicate to each edge.
+            logical_state = "WAITING_FOR_VERIFIED_EVIDENCE"
+        else:
+            logical_state = "LOGICALLY_ELIGIBLE"
+            frontier.append(node["action_id"])
+        slot = target_slots.get(node["action_id"])
+        projected.append({
+            "action_id": node["action_id"], "order": node["order"], "status": node["status"],
+            "dependencies": list(dependencies), "logical_state": logical_state,
+            "target_repository_id": slot["target"]["repository_id"] if slot else None,
+            "target_resolution": "PINNED_UNVERIFIED" if slot else "UNAVAILABLE",
+            "selected_binding_resolution": slot["selected_binding_resolution"] if slot else "UNAVAILABLE",
+            "baseline_verification": "UNVERIFIED" if slot else "UNAVAILABLE",
+            "dependency_evidence_resolution": "UNAVAILABLE" if dependencies else "NOT_REQUIRED",
+            "dispatchable": False,
+        })
+    return {
+        "contract_version": FRONTIER_CONTRACT_VERSION,
+        "source_mission_revision": mission_revision,
+        "source_slot_digest": source_slot_digest,
+        "graph_kind": "STORED_ACTION_LOGICAL_DAG",
+        "logical_frontier_action_ids": frontier,
+        "actions": projected,
+        "parallel_execution": "NOT_QUALIFIED",
+        "read_only": True,
+    }

forge_autonomy-2.12.2/forge/advisory_candidate_cli.py

@@ -0,0 +1,30 @@
+"""Private-token HTTP-equivalent Candidate commands; no admin fallback."""
+import argparse,json
+from pathlib import Path
+from .advisory_candidate_contract import CONTRACT
+from .advisory_candidate_grant import AdvisoryCandidateGrant
+from .advisory_candidate_service import AdvisoryCandidateService
+from .workspace_review_grant import _private_bytes
+
+def main(argv=None):
+    p=argparse.ArgumentParser(prog='forge-advisory-candidate');p.add_argument('--data-root',required=True);p.add_argument('--token-file',required=True);c=p.add_subparsers(dest='action',required=True);c.add_parser('capability')
+    source=c.add_parser('source');source.add_argument('--conversation-id',required=True);source.add_argument('--turn-id',required=True)
+    preview=c.add_parser('preview');preview.add_argument('--conversation-id',required=True);preview.add_argument('--proposal-id',required=True);preview.add_argument('--revision',type=int)
+    op=c.add_parser('operation');op.add_argument('--conversation-id',required=True);op.add_argument('--proposal-id',required=True);op.add_argument('--operation-id',required=True)
+    for name in ['save','register']:s=c.add_parser(name);s.add_argument('--request-file',required=True)
+    a=p.parse_args(argv)
+    try:
+        from .server_runtime import existing_instance
+        i=existing_instance(a.data_root);g=AdvisoryCandidateGrant(i.data_root,i.instance_id);t=Path(a.token_file)
+        if t.is_symlink() or t.stat().st_mode&0o077 or t.stat().st_size>256:raise ValueError('private token file required')
+        token='Bearer '+t.read_text().strip();service=AdvisoryCandidateService(i.data_root,g);method='GET';body=None
+        if a.action=='capability':target='/v1/advisory-candidates/capability'
+        elif a.action=='source':target='/v1/advisory-candidates/'+a.conversation_id+'/source/'+a.turn_id
+        elif a.action=='preview':target='/v1/advisory-candidates/'+a.conversation_id+'/proposals/'+a.proposal_id+('' if a.revision is None else '?revision='+str(a.revision))
+        elif a.action=='operation':target='/v1/advisory-candidates/'+a.conversation_id+'/proposals/'+a.proposal_id+'/registrations/'+a.operation_id
+        else:
+            body=json.loads(_private_bytes(Path(a.request_file)));method='POST';target='/v1/advisory-candidates/'+body['conversation_id']+'/proposals'+('' if a.action=='save' else '/'+body['proposal_id']+'/registrations')
+        status,out=service.handle(method,target,token,body);print(json.dumps(out,sort_keys=True));return 0 if status==200 else 1
+    except (OSError,ValueError,KeyError,RuntimeError):print(json.dumps({'contract_version':CONTRACT,'error':{'code':'CANDIDATE_CLI_UNAVAILABLE'}}));return 1
+
+if __name__=='__main__':raise SystemExit(main())

forge_autonomy-2.12.2/forge/advisory_candidate_contract.py

@@ -0,0 +1,78 @@
+"""Explicit user-authored Candidate fields and immutable advice provenance."""
+from .advisory_contract import digest,text,AdvisoryConflict
+from .approved_worklist import identifier
+from .models.mission_effect import MissionEffectPolicy
+from .lifecycle import MissionCandidate,MissionRecommendation
+
+CONTRACT='forge-advisory-candidate/v1'
+
+def revision(value):
+    if type(value) is not int or value<0:raise ValueError('invalid revision')
+    return value
+
+def hash_reference(value):
+    if not isinstance(value,str) or len(value)!=71 or not value.startswith('sha256:') or any(c not in '0123456789abcdef' for c in value[7:]):raise ValueError('invalid digest')
+    return value
+
+def exact(value,fields):
+    if not isinstance(value,dict) or set(value)!=set(fields.split()) or value.get('contract_version')!=CONTRACT:raise ValueError('closed Candidate contract required')
+    return value
+
+def fields(value):
+    names='title objective business_value engineering_value architectural_value rationale confidence scope exclusions acceptance_criteria architecture_constraints dependencies effect_policy'
+    if not isinstance(value,dict) or set(value)!=set(names.split()):raise ValueError('explicit structured fields required')
+    for k in ['title','objective','business_value','engineering_value','architectural_value','rationale']:text(value[k],1000 if k!='title' else 256)
+    if type(value['confidence']) is not int or not 0<=value['confidence']<=100:raise ValueError('explicit confidence required')
+    for k in ['scope','exclusions','acceptance_criteria','architecture_constraints','dependencies']:
+        a=value[k]
+        if not isinstance(a,list) or len(a)>8 or len(a)!=len(set(a)):raise ValueError('bounded unique fields required')
+        for v in a:text(v,1000)
+    if not value['scope'] or not value['acceptance_criteria'] or any(len(v.strip())<20 for v in value['acceptance_criteria']):raise ValueError('substantive scope and criteria required')
+    policy=MissionEffectPolicy.from_dict(value['effect_policy'])
+    if policy.mode in {'DOCUMENTATION_ONLY','ARCHITECTURE_DESIGN_ONLY'} and any(v.endswith('/') for v in policy.write_paths):raise ValueError('document proposals require exact document paths')
+    return value
+
+def proposal_request(value):
+    exact(value,'contract_version instance_id project_id repository_id conversation_id proposal_id turn_id expected_revision expected_conversation_revision context_revision fields')
+    for k in ['instance_id','project_id','repository_id','conversation_id','proposal_id','turn_id']:identifier(value[k])
+    revision(value['expected_revision']);revision(value['expected_conversation_revision']);hash_reference(value['context_revision']);fields(value['fields'])
+    return value
+
+def registration_request(value):
+    exact(value,'contract_version operation_id instance_id project_id repository_id conversation_id proposal_id proposal_revision proposal_digest expected_conversation_revision context_revision confirm')
+    for k in ['operation_id','instance_id','project_id','repository_id','conversation_id','proposal_id']:identifier(value[k])
+    if revision(value['proposal_revision'])<1:raise ValueError('proposal revision required')
+    revision(value['expected_conversation_revision']);hash_reference(value['proposal_digest']);hash_reference(value['context_revision'])
+    if value['confirm'] is not True:raise ValueError('explicit confirmation required')
+    return value
+
+def candidate_objects(proposal,key,occurred_at):
+    """Only declared user fields populate the existing governance models."""
+    if proposal.get('contract_version') == 'forge-chat-first-mission/v1':
+        from .mission_concept_registration import candidate_objects as generated_objects
+        return generated_objects(proposal,key,occurred_at)
+    f=fields(proposal['fields']);source=proposal['source'];rec_id='advice-recommendation-'+key[7:39];can_id='advice-candidate-'+key[7:39]
+    rec=MissionRecommendation(id=rec_id,title=f['title'],mission_origin=source['advisor_kind'].lower(),
+        business_summary=f['objective'],engineering_summary=f['objective'],business_value=f['business_value'],
+        engineering_value=f['engineering_value'],architectural_value=f['architectural_value'],
+        repository_evidence=tuple(source['evidence_references']),decision_evidence_reference=source['result_digest'],
+        dependencies=tuple(f['dependencies']),alternatives=(),confidence=f['confidence'],recommendation_timestamp=occurred_at,
+        known_constraints=tuple(f['exclusions']),evidence_references=(source['request_digest'],source['context_revision']))
+    candidate=MissionCandidate(id=can_id,recommendation_id=rec.id,title=f['title'],objective=f['objective'],
+        scope=tuple(f['scope']),acceptance_criteria=tuple(f['acceptance_criteria']),
+        architecture_constraints=tuple(f['architecture_constraints'])+tuple('EXCLUDED: '+v for v in f['exclusions']),
+        dependencies=tuple(f['dependencies']),effect_policy=MissionEffectPolicy.from_dict(f['effect_policy']))
+    return rec,candidate
+
+def registration_key(principal,proposal):
+    return digest([principal,proposal['project_id'],proposal['repository_id'],proposal['conversation_id'],proposal['proposal_id'],proposal['proposal_revision']])
+
+def registration_receipt(principal,operation_id,key,proposal,occurred_at):
+    if proposal.get('contract_version') == 'forge-chat-first-mission/v1':
+        from .mission_concept_registration import registration_receipt as generated_receipt
+        return generated_receipt(principal,operation_id,key,proposal,occurred_at)
+    from .approved_worklist import timestamp
+    timestamp(occurred_at)
+    if proposal['principal_reference']!=principal or registration_key(principal,proposal)!=key:raise ValueError('registration correlation differs')
+    rec,can=candidate_objects(proposal,key,occurred_at)
+    return {'contract_version':CONTRACT,'operation_id':identifier(operation_id),'principal_reference':principal,'registration_key':key,'proposal_digest':proposal['proposal_digest'],'proposal_revision':proposal['proposal_revision'],'source':proposal['source'],'candidate':can.to_dict(),'recommendation_id':rec.id,'candidate_digest':digest(can.to_dict()),'recommendation_digest':digest(rec.to_dict()),'registered_at':occurred_at,'status_at_registration':'RECOMMENDED','rationale':proposal['fields']['rationale']}

forge_autonomy-2.12.2/forge/advisory_candidate_grant.py

@@ -0,0 +1,107 @@
+"""Separate owner capability for one conversation and exact Candidate proposal IDs."""
+from dataclasses import dataclass
+from pathlib import Path
+from datetime import UTC,datetime,timedelta
+from hashlib import sha256
+import argparse,json,secrets
+from .advisory_candidate_contract import CONTRACT
+from .advisory_grant import project_scope,conversation_path
+from .approved_worklist import identifier,timestamp
+from .workspace_review_grant import _locked,_private_bytes,_write_private,_new_token
+from .workspace_worklist_control_grant import current_operator
+
+@dataclass(frozen=True)
+class CandidatePrincipal:
+    principal_id:str
+    instance_id:str
+    project_id:str
+    repository_id:str
+    conversation_id:str
+    proposal_ids:tuple
+    grant_id:str
+    maximum_registrations:int
+    @property
+    def reference(self):return self.instance_id+':'+self.principal_id
+    @property
+    def conversation_ids(self):return (self.conversation_id,)
+    @property
+    def maximum_turns(self):return 8
+
+class AdvisoryCandidateGrant:
+    def __init__(self,root,instance_id):
+        self.root=Path(root);self.instance_id=identifier(instance_id);self.path=self.root/'credentials'/'advisory-candidate'/'grants.json'
+    def _records(self,missing=False):
+        if missing and not self.path.exists() and not self.path.is_symlink():return []
+        v=json.loads(_private_bytes(self.path));names=set('principal_id instance_id project_id repository_id conversation_id proposal_ids grant_id maximum_registrations expires_at state token_digest'.split())
+        if not isinstance(v,dict) or set(v)!={'contract_version','instance_id','records'} or v['contract_version']!=CONTRACT or v['instance_id']!=self.instance_id or not isinstance(v['records'],list) or len(v['records'])>64:raise ValueError('invalid Candidate grant store')
+        records=v['records'];seen=set()
+        for r in records:
+            if not isinstance(r,dict) or set(r)!=names:raise ValueError('invalid Candidate grant')
+            for k in ['principal_id','instance_id','project_id','repository_id','conversation_id','grant_id']:identifier(r[k])
+            timestamp(r['expires_at'])
+            if r['instance_id']!=self.instance_id or r['grant_id'] in seen or r['state'] not in {'ACTIVE','REVOKED'} or type(r['maximum_registrations']) is not int or not 1<=r['maximum_registrations']<=8:raise ValueError('invalid grant binding')
+            if not isinstance(r['proposal_ids'],list) or not 1<=len(r['proposal_ids'])<=16 or sorted(set(r['proposal_ids']))!=r['proposal_ids']:raise ValueError('bounded proposal identities required')
+            for v in r['proposal_ids']:identifier(v)
+            h=r['token_digest']
+            if not isinstance(h,str) or len(h)!=64 or any(c not in '0123456789abcdef' for c in h):raise ValueError('invalid token digest')
+            seen.add(r['grant_id'])
+        return records
+    def _save(self,records):
+        raw=json.dumps({'contract_version':CONTRACT,'instance_id':self.instance_id,'records':records},sort_keys=True).encode()
+        if len(raw)>65536:raise ValueError('grant capacity exhausted')
+        _write_private(self.path,raw)
+    def issue(self,*,principal_id,project_id,repository_id,conversation_id,proposal_ids,expires_at,maximum_registrations,token_path):
+        for v in [principal_id,project_id,repository_id,conversation_id]:identifier(v)
+        if not isinstance(proposal_ids,(tuple,list)) or not 1<=len(proposal_ids)<=16 or len(set(proposal_ids))!=len(proposal_ids):raise ValueError('bounded proposals required')
+        for v in proposal_ids:identifier(v)
+        if type(maximum_registrations) is not int or not 1<=maximum_registrations<=8 or not datetime.now(UTC)<timestamp(expires_at)<=datetime.now(UTC)+timedelta(days=30):raise ValueError('bounded grant required')
+        token_path=Path(token_path)
+        if token_path.resolve()==self.path.resolve():raise ValueError('token/store collision')
+        with _locked(self.path):
+            current_operator(self.root,self.instance_id);scope=project_scope(self.root,self.instance_id)
+            if (scope['project_id'],scope['repository_id'])!=(project_id,repository_id):raise PermissionError('foreign project')
+            path=conversation_path(self.root,self.instance_id,project_id,repository_id,conversation_id)
+            if path.exists() or path.is_symlink():
+                if json.loads(_private_bytes(path))['principal_reference']!=self.instance_id+':'+principal_id:raise PermissionError('foreign advice owner')
+            records=self._records(True)
+            if len(records)>=64:raise ValueError('grant capacity exhausted')
+            token=secrets.token_urlsafe(48);r={**scope,'principal_id':principal_id,'conversation_id':conversation_id,'proposal_ids':sorted(proposal_ids),'grant_id':'candidate-'+secrets.token_hex(16),'maximum_registrations':maximum_registrations,'expires_at':expires_at,'state':'ACTIVE','token_digest':sha256(token.encode()).hexdigest()}
+            _new_token(token_path,token)
+            try:self._save([*records,r])
+            except Exception:token_path.unlink(missing_ok=True);raise
+            return {k:v for k,v in r.items() if k!='token_digest'}
+    def revoke(self,grant_id):
+        identifier(grant_id)
+        with _locked(self.path):
+            current_operator(self.root,self.instance_id);records=self._records();r=next((r for r in records if r['grant_id']==grant_id),None)
+            if r is None:raise ValueError('unknown grant')
+            r['state']='REVOKED';self._save(records);return {'grant_id':grant_id,'state':'REVOKED'}
+    def authenticate(self,authorization):
+        if not isinstance(authorization,str) or not authorization.startswith('Bearer '):return None
+        token=authorization[7:]
+        if not token or len(token)>256 or any(ord(c)<33 or ord(c)>126 for c in token):return None
+        try:
+            r=next((r for r in self._records() if secrets.compare_digest(r['token_digest'],sha256(token.encode()).hexdigest())),None)
+            if r is None or r['state']!='ACTIVE' or timestamp(r['expires_at'])<=datetime.now(UTC):return None
+            return CandidatePrincipal(**{k:r[k] for k in CandidatePrincipal.__dataclass_fields__ if k!='proposal_ids'},proposal_ids=tuple(r['proposal_ids']))
+        except (OSError,ValueError,KeyError,TypeError):return None
+    def authorize(self,authorization,conversation_id=None,proposal_id=None):
+        p=self.authenticate(authorization)
+        if p is None:raise PermissionError('Candidate credential unavailable')
+        current_operator(self.root,self.instance_id)
+        if project_scope(self.root,self.instance_id)!={k:getattr(p,k) for k in ['instance_id','project_id','repository_id']}:raise PermissionError('project changed')
+        if conversation_id is not None and conversation_id!=p.conversation_id or proposal_id is not None and proposal_id not in p.proposal_ids:raise PermissionError('foreign proposal scope')
+        return p
+
+def main(argv=None):
+    parser=argparse.ArgumentParser(prog='forge-advisory-candidate-grant');parser.add_argument('--data-root',required=True);c=parser.add_subparsers(dest='action',required=True);i=c.add_parser('issue')
+    for k in ['principal-id','project-id','repository-id','conversation-id','expires-at','token-file']:i.add_argument('--'+k,required=True)
+    i.add_argument('--proposal-id',action='append',required=True);i.add_argument('--maximum-registrations',type=int,default=1);r=c.add_parser('revoke');r.add_argument('--grant-id',required=True);a=parser.parse_args(argv)
+    try:
+        from .server_runtime import existing_instance
+        instance=existing_instance(a.data_root);g=AdvisoryCandidateGrant(instance.data_root,instance.instance_id)
+        out=g.revoke(a.grant_id) if a.action=='revoke' else g.issue(principal_id=a.principal_id,project_id=a.project_id,repository_id=a.repository_id,conversation_id=a.conversation_id,proposal_ids=a.proposal_id,expires_at=a.expires_at,maximum_registrations=a.maximum_registrations,token_path=a.token_file)
+        print(json.dumps(out,sort_keys=True));return 0
+    except (OSError,ValueError,RuntimeError,PermissionError):print(json.dumps({'contract_version':CONTRACT,'error':{'code':'CANDIDATE_GRANT_UNAVAILABLE'}}));return 1
+
+if __name__=='__main__':raise SystemExit(main())