@schift-io/knowledge-scope 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,387 @@
+# Schift Knowledge Scope CE
+
+Connect an existing Schift Search index to your AI application and return cited evidence within
+one project's declared access boundary. Your application chooses the model and generates the answer.
+
+Start with the [first retrieval](#quickstart), then use the SDK in your application. For a customer
+trial, follow the [pilot guide](docs/PILOT.md), which separates local verification from live-customer
+acceptance.
+
+```text
+scope.json + schema files
+          │ validate + lock
+          ▼
+portable KnowledgeScopeDefinition
+          │ mount
+          ▼
+server-owned KnowledgeScopeMount
+          │ declared operation only
+          ▼
+Open Connector / Schift Search / injected records port
+          │ normalize + authorize + admit
+          ▼
+CandidateEnvelope[] + admission receipt
+```
+
+## What is implemented
+
+- [x] Portable Definition and server-owned Mount are separate contracts.
+- [x] The lock covers canonical `scope.json` plus every referenced input/result schema.
+- [x] Local mount state uses owner-only, atomic file persistence and optimistic revisions.
+- [x] Authorization decisions HMAC-bind the complete immutable Candidate evidence projection and
+      survive process restarts.
+- [x] Open Connector executes declared actions through its public runtime API.
+- [x] Schift Search uses the authenticated v2 status + retrieve APIs.
+- [x] Direct named-record execution is available through an injected application port.
+- [x] Candidate admission checks source, operation, provider, permission mode, Scope, citation,
+      freshness, connector audit correlation, and required provider scopes.
+- [x] Aggregate admission enforces every declared `minEvidence` coverage assertion.
+- [x] `run-batch` combines up to eight declared operations under one mount and admits their evidence together.
+- [x] CLI and loopback HTTP API use the same application and persistent state.
+- [ ] npm publication, Schift Cloud multi-tenant persistence, production deployment, and live
+      provider-account certification. Those are separate operational actions.
+
+OBS, Context Runtime/A2A, APM, Agent execution, Workflow execution, and final LLM generation are
+deliberately outside this package.
+
+## Quickstart
+
+You need Node.js 20 or later, a package tarball, and an **already indexed** Schift Search corpus.
+Obtain the Search endpoint, authorized token, organization ID, and index name from its owner.
+This package does not upload, parse, or index your documents. A new empty index will not produce
+usable evidence.
+
+Until npm publication is completed, install the supplied artifact in your application directory.
+Replace the path with the actual tarball; do not assume the registry package is available:
+
+```bash
+npm install /absolute/path/to/schift-io-knowledge-scope-0.1.0.tgz
+npx --no-install schift-ks --help
+```
+
+Keep credentials in your local runtime environment. The values below are placeholders, not demo
+credentials:
+
+```bash
+export SCHIFT_KS_SEARCH_URL=https://api.schift.io
+export SCHIFT_KS_SEARCH_TOKEN='<authorized Search token>'
+export SCHIFT_KS_SEARCH_ORGANIZATION_ID='<your organization ID>'
+export SCHIFT_KS_SEARCH_SCOPES=search:read
+```
+
+Create a new workspace and retrieve evidence. Replace `support-handbook` and `tenant.acme` with
+the authorized index and project tenant. The destination must not already exist:
+
+```bash
+npx --no-install schift-ks quickstart ./support-project \
+  --index support-handbook --tenant tenant.acme \
+  --query 'How do I reset a subscription?'
+```
+
+The command creates portable files in `support-project/pack/`, with local `bindings.json`,
+`input.json`, and `installation.json` beside that directory. It locks, mounts, and runs the `search`
+operation. Save the returned `installationId`. `result.status: "ready"` means admitted evidence is
+available; `"insufficient_evidence"` means the application must not answer from these results.
+The outer `status: "completed"` reports completion of the command, not evidence sufficiency.
+
+Check the installation without a provider request, or explicitly probe it with another question:
+
+```bash
+npx --no-install schift-ks doctor '<installation-id>'
+npx --no-install schift-ks doctor '<installation-id>' --probe --query 'How do I reset a subscription?'
+```
+
+The default doctor report has `evidenceVerified: false`; `configured` does not certify live
+retrieval. A probe executes the normal read path and may consume provider usage. On a run failure,
+quickstart preserves the workspace and reports a recovery command rather than overwriting it.
+If filesystem setup failed, `artifactsComplete: false` means the workspace needs inspection and
+validation before mounting; the recovery command does not claim that incomplete files are ready.
+
+## Use the evidence in your application
+
+The installed package includes a consumer that uses the same local state and provider environment:
+
+```bash
+node node_modules/@schift-io/knowledge-scope/examples/consumer.mjs \
+  '<installation-id>' tenant.acme 'How do I reset a subscription?' search
+```
+
+It prints the typed result, exits with code 3 for insufficient evidence, and never calls a model.
+In your application, `createKnowledgeScopeClient({ application })` exposes `inspect(installationId)`,
+`run(request)`, `runBatch(request)`, and `admit(request)`. Inject `createCliDependencies().embedded` for the local
+application or a `createRemoteKnowledgeScopeApplication` instance for the authenticated HTTP API.
+The client validates response contracts and identity; the application remains responsible for
+authorization and HMAC verification.
+
+Only pass `result.candidates` to downstream processing when `result.status === "ready"`. Preserve
+each candidate's citation when assembling context. Your model, prompt, and answer UI remain yours.
+
+For offline retrieval measurements, see the [evaluation example](examples/evaluation/README.md)
+and the [pilot metric definitions](docs/PILOT.md#measure-a-useful-outcome). The included dataset is
+synthetic and makes no accuracy claim about a live provider.
+
+## Manual authoring
+
+For a complete editable definition, copy the shipped support example into a new directory from
+your application root. This example declares `search-handbook`, `fetch-support`, and `list-orders`;
+the matching bindings name those exact operations:
+
+```bash
+mkdir ./manual-support
+cp -R node_modules/@schift-io/knowledge-scope/examples/support-scope ./manual-support/pack
+cp node_modules/@schift-io/knowledge-scope/examples/mount-bindings.json ./manual-support/bindings.json
+```
+
+In `manual-support/bindings.json`, replace `replace-with-organization` with the same organization
+as `SCHIFT_KS_SEARCH_ORGANIZATION_ID`, and replace `replace-with-tenant` with your tenant. The sample
+Search index is `support-handbook`; if yours differs, change both the capability's `indexRef` in
+`pack/scope.json` and its Search binding's `providerRef` in `bindings.json` to your index name.
+These files contain references, never credentials.
+
+```bash
+npx --no-install schift-ks validate ./manual-support/pack
+npx --no-install schift-ks lock ./manual-support/pack
+npx --no-install schift-ks mount ./manual-support/pack --bindings ./manual-support/bindings.json
+npx --no-install schift-ks inspect '<installation-id>'
+```
+
+Use the returned installation ID in subsequent commands. Mounting records and connector bindings
+does not configure their executors; running those two operations requires the separate provider
+configuration described below. The Search operation can run independently.
+
+When a definition declares capabilities, every supplied binding must name at least one coherent
+operation and at least one declared capability must be bound. Other provider-specific capabilities
+may remain unbound and fail with `operation_not_bound` if called. A zero-capability, document-only
+definition may still mount with an empty operation list.
+
+Save this strict JSON document as `manual-support/run.json`. Replace `replace-with-tenant` with
+the **same value** used in `bindings.json`; this is not an additional access boundary:
+
+```json
+{
+  "effectiveScope": {"tenant": "replace-with-tenant"},
+  "input": {"query": "How do I reset a subscription?"},
+  "filters": {},
+  "expectedRevision": 1
+}
+```
+
+```bash
+npx --no-install schift-ks run '<installation-id>' search-handbook --input ./manual-support/run.json
+```
+
+To stop using the mount, inspect its current revision and pass that revision to
+`schift-ks unmount '<installation-id>' --expected-revision <revision>`.
+
+`schift-ks init <new-directory>` is a separate authoring tool: it creates an empty skeleton with
+no capabilities. Before attaching an operation binding, declare that operation and its referenced
+schemas yourself. Do not attach the shipped example's operation bindings to the empty skeleton.
+
+`admit` accepts either one Candidate object or a nonempty JSON array. Use an array to evaluate
+already available Candidates as one aggregate coverage set:
+
+```bash
+npx --no-install schift-ks admit '<installation-id>' --candidate ./candidates.json
+```
+
+Each `run` executes one operation against the full Scope policy and withholds all Candidates when
+coverage is insufficient. To retrieve documents and records together, declare separate required
+coverage rules for `document` and `records`, then call `run-batch` with both operations:
+
+```json
+{
+  "effectiveScope": {"tenant": "replace-with-tenant"},
+  "expectedRevision": 1,
+  "operations": [
+    {"operationId": "search-handbook", "input": {"query": "What is the shipping policy?"}},
+    {"operationId": "fetch-support", "input": {"query": "Order 123 status"}}
+  ]
+}
+```
+
+Save this as `batch.json`, with inputs matching your declared schemas and a current mount revision:
+
+```bash
+npx --no-install schift-ks run-batch '<installation-id>' --input ./batch.json
+node node_modules/@schift-io/knowledge-scope/examples/batch-consumer.mjs '<installation-id>' ./batch.json
+```
+
+The shipped support Pack is a schema example; it does not already require both classes. For a
+combined policy, add two `mustConsider` rules and list both IDs in `evidence.coverageAssertions`.
+Bind the actual record operation as `sourceClass: "records"`; the sample helpdesk binding is
+`activity_stream` and must not be relabeled unless its source really supplies records.
+
+Batch requests contain 1–8 unique operation IDs. All inputs and bindings are validated before
+provider dispatch; execution is sequential, with a combined ceiling of 100 Candidates and 8 MiB.
+Admission rechecks the current mount before releasing the combined evidence. A failed operation or
+unsatisfied policy releases no partial Candidate payload. Separate insufficient runs cannot be
+accumulated through `admit`, because those runs withhold their Candidates.
+Every requested operation must contribute evidence. Even if the remaining operations satisfy
+coverage, an empty operation fails with `batch_incomplete`; rejected Candidates fail with
+`candidate_invalid`. Neither error includes partial evidence.
+
+This is atomic admission and output, not a shared transaction or synchronized snapshot across
+external providers. Each source retains its own revision and freshness. Python provides matching
+request contracts and pure admission checks; this package's execution runtime and CLI are Node.js.
+See the [combined pilot path](docs/PILOT.md#extend-to-documents-plus-live-records).
+
+All successful output is JSON on stdout. Errors are redacted JSON on stderr with a stable `code`
+and a non-zero exit status.
+
+## Provider configuration
+
+Provider URLs and credentials are runtime configuration. They are never written to `scope.json`,
+the lock, mount state, Candidate output, or errors.
+
+Open Connector is the product in `core-dependencies/schift-connector`; it owns account connections,
+credentials, and its public action runtime. Configure its endpoint:
+
+```bash
+export SCHIFT_KS_OPEN_CONNECTOR_URL=http://127.0.0.1:3000
+export SCHIFT_KS_OPEN_CONNECTOR_TOKEN=...
+export SCHIFT_KS_OPEN_CONNECTOR_SCOPES=tickets:read
+export SCHIFT_KS_OPEN_CONNECTOR_ALIAS=work
+export SCHIFT_KS_OPEN_CONNECTOR_READ_ACTIONS='[{"connectorRef":"zendesk","connectorAlias":"work","actionId":"zendesk.search_tickets"}]'
+```
+
+`SCHIFT_KS_OPEN_CONNECTOR_READ_ACTIONS` is a strict server-owned JSON allowlist of connector,
+account alias, and action triples. A Pack cannot authorize its own action or select a different
+account with the same action ID; any triple not explicitly attested as retrieval-only is rejected
+before HTTP.
+The generic Open Connector adapter never drops an allowed filter or narrower Scope silently.
+Nonempty filters and `namespace` / `subject` / `session` Scope require an injected trusted input
+mapper in the SDK; without one, execution fails before HTTP. The mapper receives trusted Scope and
+must bind it into the provider-native, schema-validated action input. Tenant-only calls may use the
+mounted connector/account boundary directly.
+
+Schift Search:
+
+```bash
+export SCHIFT_KS_SEARCH_URL=https://api.schift.io
+export SCHIFT_KS_SEARCH_TOKEN=...
+export SCHIFT_KS_SEARCH_ORGANIZATION_ID=org.acme
+export SCHIFT_KS_SEARCH_SCOPES=search:read
+```
+
+The Schift Search adapter first reads `/v2/buckets/{index}/search/status`, then retrieves passages
+from `/v2/buckets/{index}/retrieve`. Missing source identity, revision, citation, or freshness fails
+closed. The credential-bound organization ID must match the mounted organization and is sent as
+`X-Org-Id`, so the Search API's normal organization/bucket ACL remains authoritative. The local
+tenant/effective Scope is an additional Schift KS constraint; it is not presented as a provider
+tenant attestation. The adapter never falls back to another index or to Web search.
+The current v2 Search API does not enforce `namespace`, `subject`, or `session` narrowing, so this
+adapter rejects those requests before HTTP. Use an appropriately scoped bucket and installation
+for separate access boundaries; adding an arbitrary Scope field does not filter provider data.
+
+For `records_operation`, library consumers inject the named-operation executor through the public
+provider port. The default CLI does not invent SQL, accept raw predicates, or hold database
+credentials; an unconfigured records operation returns `invalid_configuration`. Open Connector may
+also be used as the managed database gateway.
+
+`web_search` remains a portable provider declaration for compatible runtimes, but the local CE
+control plane does not silently choose or bill a Web provider in v0.1. It fails closed with
+`invalid_configuration`; applications can use Schift Search, Open Connector, or an injected records
+port until a separately governed Web-search adapter is installed.
+
+## Local HTTP API
+
+Start the same application as a loopback service:
+
+```bash
+export SCHIFT_KS_ORGANIZATION_ID=org.acme
+export SCHIFT_KS_TENANT=tenant.acme
+export SCHIFT_KS_API_TOKEN='<random owner-only token>'
+node dist/main.js serve --host 127.0.0.1 --port 8787
+```
+
+Routes:
+
+- `POST /v1/knowledge-scopes/mounts`
+- `GET /v1/knowledge-scopes/mounts/{installationId}`
+- `POST /v1/knowledge-scopes/mounts/{installationId}/unmount`
+- `POST /v1/knowledge-scopes/mounts/{installationId}/capabilities/{operationId}:run`
+- `POST /v1/knowledge-scopes/mounts/{installationId}:run-batch`
+- `POST /v1/knowledge-scopes/mounts/{installationId}:admit`
+
+The HTTP mount body cannot choose organization or tenant; the server injects them from trusted
+configuration. Mutating requests require `application/json`, and cross-origin browser requests are
+rejected.
+
+The local HTTP server always requires `SCHIFT_KS_API_TOKEN`, including on loopback, and validates
+the literal loopback Host to prevent DNS rebinding. Direct non-loopback binding is not supported in
+v0.1 because the built-in server is plain HTTP. The same token is sent by
+`schift-ks ... --api-url <url>`; non-loopback remote URLs must use HTTPS. The token is never
+persisted or printed. Production exposure should terminate TLS and apply network policy at an
+authenticated reverse proxy that forwards only to the loopback listener, or use a Schift Cloud
+adapter.
+
+## Portable files and schema subset
+
+The portable directory contains exactly:
+
+- `scope.json`
+- every relative `inputSchemaRef` and `resultSchemaRef`
+- generated `scope.lock.json`
+
+Symlinks, absolute paths, backslashes, `..`, duplicate JSON keys, missing files, and every undeclared
+regular file are rejected. `.schift/` is local state and is never locked or packed; README, license,
+credential, PDF, and raw-data files belong outside the portable Scope directory.
+
+The dependency-free schema validator supports:
+
+`type`, `properties`, `required`, `additionalProperties` (boolean), `items`, `enum`, `const`,
+`minLength`, `maxLength`, `minimum`, `maximum`, `minItems`, and `maxItems`.
+
+`$ref`, composition keywords, conditionals, formats, unknown keywords, and schema/value nesting
+beyond 16 levels fail with `unsupported_schema_keyword` or `schema_depth_exceeded`.
+Portable schema numbers are restricted to the cross-runtime safe-integer range. Integral spellings
+such as `1`, `1.0`, and `1e0` normalize to one lock value; fractional and unsafe integers are
+rejected instead of producing different TypeScript/Python digests.
+
+## State and trust guarantees
+
+- `SCHIFT_KS_HOME` defaults to `~/.schift/knowledge-scope`.
+- Directories are mode `0700`; state and the separate 32-byte authorization key are mode `0600`.
+- State uses same-directory temp files, fsync, atomic rename, and an exclusive process lock.
+- State is capped at 16 MiB and is parsed with the same byte/depth/node ceilings before and after
+  every atomic write, so a successful mount cannot make the next read invalid.
+- Lock recovery is intentionally fail-closed. If a process crashes while holding `state.lock`, the
+  owner must verify the recorded PID is gone before manually removing that lock file; the product
+  never auto-deletes a possibly live writer's lock.
+- Unmount preserves a tombstone, removes active bindings, and increments mount revision.
+- Replacing the authorization key intentionally invalidates outstanding Candidates.
+- Provider output cannot set installation, authority, Scope, Pack digest, permission mode, or the
+  authorization decision. The HMAC covers SRN, revision, freshness, payload, citation, provider
+  scopes/evidence, mounted permission, and every Scope/binding identity used by admission.
+- A denied or incomplete run returns no Candidate payloads.
+
+## Verification
+
+From a clean repository checkout, use the canonical verification command. It installs dependencies
+inside a temporary copy before building and testing:
+
+```bash
+cd packages/knowledge-scope-cli
+bun run release:verify
+```
+
+For an already provisioned development workspace, these individual checks are also available.
+They require its dependencies, including TypeScript, to have been installed:
+
+```bash
+bun run build
+bun run typecheck
+bun test
+node dist/main.js --help
+```
+
+The repository E2E suite executes Open Connector and Schift Search against local fake HTTP
+providers. Release verification additionally dry-packs the artifact, audits its file inventory,
+installs it in an empty temporary project, and repeats the portable lifecycle from that installed
+artifact. `release:verify` performs these checks in an isolated temporary copy with its own
+dependencies and writes a tarball, SHA-256 checksum, and `release-report.json` to the reported
+temporary directory. It does not publish a package or deploy a service.
+
+Local fake-provider tests verify software contracts. They do not certify a customer's Search
+index, connector account, access policy, or retrieval quality. Use the [pilot gates](docs/PILOT.md#external-pilot-gates)
+for those checks.