create-egregore 0.21.6 → 0.22.0

package/runtime/codex/docs/spirit-discovery.md

@@ -0,0 +1,96 @@
+# Capability and system discovery
+
+Each harness reads the same evidence through a fixed adapter:
+
+```sh
+bash bin/spirit-discovery-claude.sh capabilities.list
+bash bin/spirit-discovery-codex.sh capabilities.find research
+bash bin/spirit-discovery-pi.sh capabilities.describe tool.spirit-query
+bash bin/spirit-discovery-prime.sh system.explain
+```
+
+Pi and Prime also register `egregore_discover_capabilities`. Prime's Python
+bridge provides `capabilities_list`, `capabilities_find`, `capabilities_describe`,
+`capabilities_explain` and `system_explain`.
+
+The generic `bin/spirit-discovery.sh` selects a runtime only when exactly one
+valid installed snapshot exists. Multiple snapshots produce `ambiguous`; use the
+fixed adapter for your current harness. A runtime label selects installation
+evidence. It confers no permission.
+
+The operations are `capabilities.list`, `capabilities.find <text>`,
+`capabilities.describe <id>`, `capabilities.explain <id>` and
+`system.explain [id]`. `--json` reads the corresponding request from stdin:
+`{"operation":"capabilities.find","query":"research"}`. Only operation-specific
+`operation`, `query` and `id` fields are accepted; duplicate fields are rejected.
+No request selects an actor, endpoint, file, policy or source map.
+Malformed Unicode and excessively nested JSON are rejected with a bounded error
+envelope and no diagnostic traceback.
+
+Responses use `egregore.capability-query/v1`. The `views` array keeps local
+installation evidence separate from optional authenticated Durable host evidence.
+There is no combined ready badge. All responses have `execution_authority: false`.
+Local callability remains false, even when a remote binding says it is callable
+in the remote observed scope.
+
+The local view reads an OSS-only build snapshot at
+`bin/data/capabilities/<runtime>.json`. It checks the snapshot and its referenced
+current files against the existing local installer ownership record. Modified,
+missing, unrecorded, conflicting and unreadable evidence remain explicit. The
+snapshot's internal digest detects inconsistency; it is not publisher authentication.
+Its raw file hash is separately compared with the installer record.
+
+The installed facet covers the enumerated delivered files. A capability with
+unmeasured package/service dependencies is partial even when those files match.
+The runtime import dependency closure is not enumerated; its explicit coverage
+gap remains even when a tool's listed files match. File evidence does not prove
+the whole capability can run.
+The current registry, caller permission, operational success, evaluation evidence
+and adoption of an authenticated release are independent facts and remain unknown
+when no owner supplies them. An org-owned replacement cannot inherit verification
+from the replaced framework files. Source checkouts without installer records
+remain unrecorded. Connect overlays are not enumerated by this OSS reader.
+
+An optional `.egregore/spirit-discovery/binding.json` enables the Durable view.
+This private, regular, unlinked file is provisioned by the operator; discovery
+never creates it. Its exact fields are `schema` (`egregore.discovery-binding/v1`),
+`org_id`, `installation_key`, `actor_id`, `origin`, `remote_runtime_actor_id`,
+`bridge_token_env` and `actor_token_env`. The last two name environment variables;
+they do not contain credentials. The binding must match the current persisted
+Runtime actor and installation. The HTTP response must independently identify the
+freshly authenticated remote Runtime actor. Remote deployment identity currently
+remains unknown. A local filesystem owner can change their own configuration;
+these checks do not sandbox that owner.
+
+Discovery uses the Runtime identity owner's `require_existing` resolution path.
+It requires canonical retained account, actor, membership and organization IDs;
+it cannot migrate, mint, lock or write identity state. The resolver reads only
+bounded config/state files and never opens referenced identity documents. Its
+`profile-config-only-sha256` revision covers configuration, and cannot substitute
+for the ordinary profile revision covering declared identity documents. The
+installation key uses that already validated organization ID without rereading
+config; installation-root and Git-backlink behavior retains its existing scope.
+
+The origin permits HTTPS, or numeric-loopback HTTP for local hosts. Credentials
+are sent only to that fixed origin. Redirects are rejected. A disposable transport
+child bounds the complete HTTP operation, including DNS resolution and trickling
+responses, to seven seconds; response bytes are capped. Credentials travel on
+stdin and never appear in arguments or output. Discovery makes no model/provider
+calls, starts no jobs, probes no capabilities and writes no state.
+
+The remote adapter accepts the exact supported v1 response shape, including
+typed facets, bindings, generation and source evidence, and bounded standard
+JSON Schema with local references. Extra fields, unsupported schema extensions,
+malformed values or expired evidence make the remote view unavailable. Accepted
+native contracts are preserved in full; response-shape validation does not
+independently attest the host's claims or inspect arbitrary prose for secrets.
+
+Local reads use descriptor-relative, no-symlink traversal. Snapshots are capped at
+2 MB, 512 entries and 4096 file references; cumulative inspected payload bytes are
+capped at 16 MB per query. Files exceeding remaining coverage are unreadable for
+that query. Queries report coverage limits rather than interpreting an incomplete
+view as proof of absence.
+
+For source architecture investigation use the separate source-only
+`bin/spirit-map.mjs` workflow. It is not imported by this reader or shipped as an
+installed system authority. Organizational recall continues through Runtime search.

package/runtime/codex/egregore_runtime/__init__.py

@@ -16,6 +16,7 @@ from .contracts import (
     CanonicalArtifact,
     Capability,
     Entitlements,
+    ExecutionAuthority,
     EgregoreProfile,
     EvidenceItem,
     GraphProjection,
@@ -47,7 +48,8 @@ from .contracts import (
 )
 from .errors import AuthorizationDenied, ContextBudgetError, EgregoreRuntimeError
 from .observe import DefaultOrgContextCompiler
-from .policy import ActorGrant, StaticPolicy, all_access_dogfood_policy, scope_allows_path
+from .policy import ActorGrant, StaticPolicy, allows, check, policy_for
+from .access import authorization_inputs, AuthorizationInputs, Principal, PRINCIPAL_KINDS
 from .telemetry import (
     ALLOWED_METRIC_KEYS,
     TELEMETRY_SCHEMA_VERSION,
@@ -140,7 +142,7 @@ from .ingest import (
     LocalQuarantine,
     NormalizedIngest,
 )
-from .runtime import EgregoreRuntime, local_runtime
+from .runtime import EgregoreRuntime, authenticated_member_runtime, local_runtime
 from .questions import (
     QUESTION_SCHEMA_VERSION,
     CanonicalQuestionService,
@@ -200,16 +202,20 @@ from .lifecycle import (
     LifecycleTransition,
     ObligationState,
 )
-from .threads import (
-    THREAD_CONFIRMATION,
-    THREAD_EVENT_SCHEMA_VERSION,
-    THREAD_SCHEMA_VERSION,
-    CanonicalThreadService,
-    ThreadError,
-    ThreadFoldReceipt,
-    ThreadSnapshot,
-    parse_thread_markdown,
-)
+from .optional_modules import optional_module as _optional_module
+
+# Threads are held out of installs (runtime.thread is queued in placement).
+if _optional_module(".threads") is not None:
+    from .threads import (
+        THREAD_CONFIRMATION,
+        THREAD_EVENT_SCHEMA_VERSION,
+        THREAD_SCHEMA_VERSION,
+        CanonicalThreadService,
+        ThreadError,
+        ThreadFoldReceipt,
+        ThreadSnapshot,
+        parse_thread_markdown,
+    )
 from .scrolls import (
     EXACT_SHARE_CONFIRMATION,
     SCROLL_EVENT_SCHEMA_VERSION,