Complete checked-method reuse and MCP compatibility for the coordinated preview

.github/dependabot.yml

@@ -11,3 +11,7 @@ updates:
     schedule:
       interval: weekly
     open-pull-requests-limit: 5
+    groups:
+      codeql-action:
+        patterns:
+          - "github/codeql-action/*"

.github/workflows/codeql.yml

@@ -29,13 +29,13 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+        uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
         with:
           languages: python
           build-mode: none
           queries: security-extended
 
       - name: Analyze
-        uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+        uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
         with:
           category: /language:python

.gitignore

@@ -9,3 +9,9 @@ __pycache__/
 build/
 dist/
 .limitless/
+my-submissions/
+BUGGER.json
+BUGGER.md
+BUGGER.lock
+BUGGER.json.bak
+.bugger.toml

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Limitless Library is pre-alpha. Small changes that preserve the fail-closed
+Limitless Library is alpha. Small changes that preserve the fail-closed
 trust model are easiest to review.
 
 1. Open an issue describing the receiver problem and the invariant affected.
@@ -15,5 +15,13 @@ trust model are easiest to review.
 6. Never commit real receiver repositories, credentials, private catalog data,
    internal experiment evidence, or generated adoption receipts.
 
+For source-free method authoring, begin with `examples/publication/method.json`.
+Readable drafts can be converted locally with
+`limitless seal-method --draft INPUT --output NEW_FILE`. The command validates
+the method and writes canonical UTF-8 JSON without overwriting or publishing.
+Point the publication draft at the sealed file. Method object bytes, rather than
+only their parsed JSON meaning, are bound by the signed publication intent;
+changing them after preparation requires a new publication operation.
+
 Contributions are accepted under Apache-2.0. By submitting a contribution, you
 represent that you have the right to license it under those terms.

README.md

@@ -127,6 +127,12 @@ scanner for secrets embedded in free text. See the
 [local demo evidence map](docs/LOCAL-DEMO.md) for the generated artifacts and
 manual inspection commands.
 
+The terminal shows `USEFUL LOCAL RESULT`: the sample authorization and token
+fields are redacted while its agent, action, and repository fields survive.
+The same run reports a verified exact component, source-free guidance, and an
+abstention. These are deterministic examples from the bundled local catalog.
+Live service queries use the current public catalog and may correctly abstain.
+
 ## How verified reuse works
 
 For exact reuse, the receiver—not the capsule—controls the trust boundary:
@@ -196,12 +202,30 @@ Start the bounded local stdio server:
 limitless-mcp --catalog examples/catalog
 ```
 
-It exposes `limitless_query_before_work` and supports stateless MCP
+It exposes `limitless_query_before_work` and `limitless_register_method` and supports stateless MCP
 `2026-07-28` requests plus the `2025-06-18` and legacy `2025-03-26`
 initialization flows. Initialization-era clients complete `initialize` and
-`notifications/initialized` before requesting a tool. MCP is a decision
-channel, not an artifact transport; installation remains an explicit
-receiver-local operation.
+`notifications/initialized` before requesting a tool. Agents query before
+material work. After checking a useful original result, they can register a
+concise source-free method with steps, checks, applicability, and limits. The
+method object follows the
+[canonical method example](examples/publication/method.json). The default stores
+it privately under `$XDG_DATA_HOME/limitless-library/methods`
+(or `~/.local/share/limitless-library/methods`). Repeating the same registration
+returns the same method reference. A registration does not assert that the
+service has verified the method or accepted it into its catalog. Query results
+remain a decision channel, not an artifact transport; installation remains an
+explicit receiver-local operation.
+
+An owner who wants new methods submitted to the public service can activate
+the service, inspect and review its publication policy, then configure the MCP
+command with **both** `--submit-methods-publicly` and
+`--public-method-policy-digest sha256:<reviewed digest>`. This is standing
+authorization to publish independently authored CC0 methods. The tool queues
+submission in a separate process so normal task completion does not wait for
+network or admission; the service still decides whether to admit each method.
+Local-only is the default. The [managed-service guide](docs/MANAGED-SERVICE.md)
+explains status, retries, and revocation.
 
 Python callers can use `query_local(...)` or `McpStdioConnector`. See
 [Protocol](docs/PROTOCOL.md).
@@ -222,8 +246,8 @@ limitless agent-connect antigravity --catalog /absolute/path/to/catalog
 The command adds one named `limitless-library` stdio server to Antigravity's
 documented MCP profile. It uses the exact Python environment that ran
 `limitless`, so there is no separate executable to find or PATH assumption to
-maintain. Restart Antigravity CLI, then its MCP instructions and the
-`limitless_query_before_work` tool are available before material work.
+maintain. Restart Antigravity CLI, then its MCP instructions and the query and
+method registration tools are available.
 
 ```bash
 limitless agent-status antigravity
@@ -271,14 +295,29 @@ command; from a source checkout, use `./scripts/limitless` instead.
 ```bash
 limitless service-activate
 limitless service-inspect
-limitless service-query --request ./service-query.json
+limitless service-query \
+  --request-id request:example-001 \
+  --objective "Verify prior work with receiver-owned checks and observed adoption" \
+  --receiver ./examples/receiver-context.json
 
 # When the verified result selects an exact artifact:
 limitless service-query \
-  --request ./service-query.json \
+  --request-id request:example-002 \
+  --objective "Find an exact component compatible with this receiver" \
+  --receiver ./examples/receiver-context.json \
   --artifact-output ./selected.bin
 ```
 
+Inspect and adapt [the service receiver example](examples/receiver-context.json)
+to the actual target before querying. It declares an agent on Linux/x86_64;
+it is not automatic host detection. `execution` describes the agent host,
+`targets` describes where the work must fit, and `allowedUse` states its intended
+use. For multiple targets, choose `all-targets` with `selectedTarget: null`, or
+`one-target` with a declared target ID. The `{constraints, toolchain}` receiver
+inside `examples/requests/` belongs to local queries and cannot be passed as a
+service receiver. The client builds fresh timestamps and a query digest; advanced
+callers can still submit a complete current query with `--request PATH`.
+
 The service accepts anonymous activation, queries, outcome evidence, and
 public contributions. A contribution can contain an independently authored
 source-free method or a canonical exact file bundle that keeps its declared
@@ -317,7 +356,20 @@ contribution is reported honestly rather than mistaken for a network failure.
 The client does not scan or upload a workspace. Artifact sources must already
 be canonical
 `limitless.exact-file-bundle/1.0` payloads; the client verifies that shape
-locally and binds it into the current signed publication intent. See the
+locally and binds it into the current signed publication intent. Method files
+also require validated canonical JSON: sorted object keys, compact UTF-8 JSON,
+and at most one trailing newline. The bundled method already meets that rule.
+For a hand-formatted method, create a new canonical file locally:
+
+```bash
+limitless seal-method --draft ./my-method.json --output ./my-method.canonical.json
+```
+
+Name that new file in the publication draft's `objects` list. `seal-method`
+does not connect or publish, and refuses to overwrite a file. Publication
+rejects malformed or noncanonical methods before signing new state or uploading;
+it never rewrites bytes already named by a resumable operation. Auxiliary
+manifest and verification files retain their own byte contracts. See the
 [managed-service connector](docs/MANAGED-SERVICE.md).
 
 ## Authoring

docs/CONFORMANCE.md

@@ -13,8 +13,9 @@ by `tests/`:
 - exact installed byte equality and rollback after failed verification;
 - receiver-runtime invocation plus receiver-owned functional obligations;
 - immutable, content-bound adoption evidence;
-- MCP 2026 discovery, read-only tool metadata, structured decisions, request
-  binding, protocol rejection, response size limits, and deadlines;
+- MCP 2026 discovery, query read-only and method-registration tool metadata,
+  structured decisions, request binding, protocol rejection, response size
+  limits, and deadlines;
 - MCP 2025-06-18 and 2025-03-26 initialization, notification admission, and
   stdio lifecycle coverage.
 

docs/MANAGED-SERVICE.md

@@ -55,22 +55,28 @@ limitless service-status
 limitless service-inspect
 ```
 
-An agent or integration can submit a complete bounded service-query record:
-
-```bash
-limitless service-query --request ./service-query.json
-```
-
-Or let the client bind the query envelope around an explicit objective and
-receiver context:
+Let the client bind a fresh query envelope around an explicit objective and
+the bundled receiver context, after adapting its facts to your actual receiver:
 
 ```bash
 limitless service-query \
   --request-id request:example-001 \
-  --objective "Add a reviewed clipboard history extension" \
-  --receiver ./receiver-context.json
+  --objective "Verify prior work with receiver-owned checks and observed adoption" \
+  --receiver ./examples/receiver-context.json
 ```
 
+The example describes an agent on Linux/x86_64. It declares `receiverId`,
+`allowedUse`, `interfaces`, `execution`, `targets`, `compatibilityMode`, and
+`selectedTarget`. It differs from the local query receiver's `constraints` and
+`toolchain`. Execution facts describe the host; target facts describe where the
+result must work. Keep those facts distinct when they differ. A malformed
+receiver fails locally with exit status 2 and an actionable message.
+
+The client fills the current timestamps, policy vocabulary, supported result
+version, and query digest. Advanced callers with an already-built current query
+can use `limitless service-query --request PATH`; no static, expiring query file
+is needed for the walkthrough. Live catalog results may include abstention.
+
 Baseline public access requires no user credential: the client automatically
 uses its pseudonymous installation session. A caller may still supply an
 explicit advanced bearer through `LIMITLESS_SERVICE_TOKEN`; bearer material is
@@ -130,7 +136,9 @@ same invocation:
 
 ```bash
 limitless service-query \
-  --request ./service-query.json \
+  --request-id request:example-artifact-001 \
+  --objective "Find an exact component compatible with this receiver" \
+  --receiver ./examples/receiver-context.json \
   --artifact-output ./selected.bin
 ```
 
@@ -206,6 +214,20 @@ an immutable mode-0600 state file beside the draft. A retry reuses that intent
 and request identity, so an interrupted transfer cannot silently become another
 release.
 
+Method objects are strict JSON with `summary`, ordered `steps`, `constraints`,
+`evaluation`, and `limitations`. The client validates structure and canonical
+bytes before it signs a new intent or uploads. Object keys must be sorted,
+whitespace must be compact, and one final newline is allowed. Constraints and
+limitations may be empty; evaluation must contain at least one check. Nonempty
+text lists must be sorted and unique. Duplicate JSON keys are rejected.
+
+For a readable draft, run
+`limitless seal-method --draft ./my-method.json --output ./my-method.canonical.json`
+and name the new file in the publication draft. Sealing is local, creates an
+owner-only file, and refuses overwrite. Automatic method admission is bounded
+to 64 KiB. Auxiliary manifest and verification objects retain their own byte
+contracts. Existing signed state always binds its original bytes.
+
 The client sends the signed policy acceptance and intent as bounded JSON,
 receives a signed plan and short-lived content authorization, and streams only
 objects the plan says are missing.
@@ -231,9 +253,9 @@ generation. Older releases stay opaque rather than being retroactively
 classified from their bytes or provenance.
 
 The bundled example is directly publishable from a supported release after the
-publisher reviews and accepts the currently advertised policy digest. The open
-client validates the public wire lifecycle but does not
-contain the private admission engine, ranking service, or managed storage.
+publisher reviews and accepts the currently advertised policy digest. The client
+validates the public wire lifecycle. Admission, ranking, and managed storage are
+provided by the service.
 
 The returned owner-only state is also the durable handle for follow-up:
 
@@ -249,6 +271,42 @@ An already revoked release returns its existing state without creating another
 withdrawal request. Pending, quarantined, rejected, or retired work cannot be
 misrepresented as an active release eligible for withdrawal.
 
+Publication state prepared by an older client for multiple targets retains its
+original authenticated target order, digest, signature, and submission reference.
+It can resume without preparing a replacement operation. New builders choose
+canonical UTF-8 target order before signing; readers never reorder an existing
+signed record. The service may still require manual admission review for multiple
+targets. Compatibility does not turn pending intake into automatic admission.
+
+### MCP method contribution
+
+The generic Library MCP also offers `limitless_register_method` after an agent
+has checked useful original work. By default it records a canonical,
+source-free method in an owner-private local store and makes no service
+request. The registered method must describe the observed outcome and its
+applicability; this note is self-reported evidence, not verified receiver
+adoption. The server exposes no exact-source contribution tool.
+
+For standing public-method authorization, activate the service, inspect its
+signed `publicationPolicy`, review its policy URL, and configure the MCP server
+with both `--submit-methods-publicly` and
+`--public-method-policy-digest sha256:<reviewed digest>`. A registration then
+queues the existing signed `service-publish` lifecycle in a background process.
+The agent receives a stable `method:<sha256>` reference immediately. Public
+admission can remain pending, be rejected, or require owner attention; the tool
+does not report those as verified success.
+
+The default store is `$XDG_DATA_HOME/limitless-library/methods`, falling back to
+`~/.local/share/limitless-library/methods`. Each method folder is named by the
+64 hex characters after `method:`. It contains `capture.json`, `method.json`,
+and, when public sharing was authorized, `publication.json` plus
+`submission-status.json`. The signed `publication.json.state.json` appears
+after the first successful service preflight. The owner can use that state file
+with `service-publication-status` or `service-publication-revoke` as above.
+Changing the advertised policy requires a new owner review and MCP policy
+digest. Retry pending or failed submissions without another agent turn using
+`python -m limitless_library.method_capture --sync <method-store> --policy-digest sha256:<reviewed digest>`.
+
 ## Advanced alternate profiles
 
 Operators building another compatible service can bypass the official
@@ -276,9 +334,10 @@ implementations.
 
 ## Deliberate exclusions
 
-Connecting does not publish work. Only `service-publish` transfers the exact
-objects named in its reviewed draft; it does not enumerate a workspace or
-upload a local catalog. The client also does not install a staged component,
+Connecting alone does not publish work. `service-publish` transfers the exact
+objects named in its reviewed draft; owner-authorized MCP method contribution
+uses that same bounded lifecycle. Neither path enumerates a workspace or
+uploads a local catalog. The client also does not install a staged component,
 hand off to a native provider, or submit local outcome evidence. Those remain
 separate owner-authorized continuations. The service-side identity authority,
 managed admission implementation, ranking, persistence, analytics, and