@schift-io/knowledge-scope 0.1.0 → 0.2.0

package/README.md

@@ -1,61 +1,88 @@
 # 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.
+Public source, contribution instructions, and releases:
+[schift-io/knowledge-scope](https://github.com/schift-io/knowledge-scope).
+
+Retrieve cited passages from your own Markdown or text files, then pass admitted evidence to your
+AI application. Your application chooses the model and generates the answer.
+
+The local-file quickstart requires **0.2.0 or later**. If you use `0.1.0`, upgrade first or use the
+[hosted Search path](#hosted-search-advanced).
 
 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.
 
+## Quickstart
+
+Start with a synthetic support handbook; no Schift account, API token, cloud service, or model is
+needed. You need Node.js 20 or later. Run these commands in your application directory:
+
+```bash
+npm install @schift-io/knowledge-scope@0.2.0
+npx --no-install schift-ks quickstart ./support-project \
+  --source ./node_modules/@schift-io/knowledge-scope/examples/local-documents/support-handbook.md \
+  --query '환불 규정'
+```
+
+The destination must be new. Expect `result.status: "ready"` with a passage about the synthetic
+14-day refund window and a citation identifying its source and line range. Local citations use
+`schift://local-documents/...#Lx-Ly`; they identify snapshot evidence, not a public web page or
+file-opening link. The result also includes the original `sourcePath`, whose current contents may
+have changed since import. This is retrieved evidence, not an AI-generated answer. Keep the
+returned `installationId` to ask again:
+
+```bash
+npx --no-install schift-ks query '<installation-id>' --query '배송 기간'
+```
+
+Next, substitute your own UTF-8 `.md` or `.txt` file, or a folder containing those files:
+
+```bash
+npx --no-install schift-ks quickstart ./my-project \
+  --source ./my-documents --query '환불 규정'
+```
+
 ```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
+Your text files -> private local snapshot -> cited evidence -> your application's chosen model
 ```
 
-## What is implemented
+This path uses lexical search, not embeddings, semantic retrieval, or reranking. Use words present
+in the source. A matching passage is not proof that it answers the question. `insufficient_evidence`
+means your application should withhold an answer, not bypass admission.
 
-- [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.
+The source text is copied into a private local snapshot outside the portable Pack. Keep local
+state private; do not publish it with the Pack. Editing the original files does not update an
+existing snapshot. To refresh, run quickstart with a new project directory and use its new
+installation. This is not continuous sync or live document-ACL enforcement. Local filesystem
+access is the security boundary; a tenant label is not user authentication.
 
-OBS, Context Runtime/A2A, APM, Agent execution, Workflow execution, and final LLM generation are
-deliberately outside this package.
+The generated policy accepts snapshots for 24 hours after import. After that, import again into a
+new workspace; editing a timestamp is not a refresh. Unmounting revokes the installation but does
+not delete its retained local snapshot. Only ingest trusted, stable local files: symlinks, hardlinks,
+special files, and files changed during capture are rejected.
 
-## Quickstart
+Limits are 100 files, 1 MiB per file, 8 MiB total text, and 4,000 chunks. A single line may contain
+at most 2,000 characters. Folder scans stop at 2,000 entries or 16 levels; hidden entries and
+`node_modules` are ignored, and other file extensions inside a folder are skipped. An explicitly
+selected unsupported file or a folder with no usable text fails with a recovery message.
+
+PDF, Office files, URLs, crawling, and an MCP adapter are not bundled. Convert supported material
+to approved text outside this package, or use an already populated Search index below. For the
+sample's expected passages and a no-model application command, see the
+[local document example](examples/local-documents/README.md).
 
-You need Node.js 20 or later, a package tarball, and an **already indexed** Schift Search corpus.
+## Hosted Search (advanced)
+
+You need Node.js 20 or later 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
+This hosted path 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:
+Install the published package in your application directory:
 
 ```bash
-npm install /absolute/path/to/schift-io-knowledge-scope-0.1.0.tgz
+npm install @schift-io/knowledge-scope@0.2.0
 npx --no-install schift-ks --help
 ```
 
@@ -99,7 +126,20 @@ validation before mounting; the recovery command does not claim that incomplete
 
 ## Use the evidence in your application
 
-The installed package includes a consumer that uses the same local state and provider environment:
+For the local-file path, run the included consumer from your application directory.
+The default local tenant is `local-tenant`; use the returned tenant if you supplied `--tenant`:
+
+```bash
+node node_modules/@schift-io/knowledge-scope/examples/consumer.mjs \
+  '<installation-id>' local-tenant '환불 규정' search
+```
+
+`createCliDependencies().embedded` loads the same local state used by the CLI, including local
+document snapshots. Keep the same `SCHIFT_KS_HOME` if you override the state directory. No model
+credentials are needed to inspect the evidence; your application controls whether to send private
+passages to an external model.
+
+For a hosted Search installation, use its authorized tenant and provider environment instead:
 
 ```bash
 node node_modules/@schift-io/knowledge-scope/examples/consumer.mjs \
@@ -120,6 +160,35 @@ For offline retrieval measurements, see the [evaluation example](examples/evalua
 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.
 
+## What is implemented
+
+```text
+scope.json + schemas -> validate + lock -> portable definition
+  -> mount with private bindings -> declared operation
+  -> local documents / Open Connector / Schift Search / injected records
+  -> normalize + authorize + admit -> cited evidence for your application
+```
+
+- [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.
+- [x] Local Markdown/text quickstart and repeated queries with cited snapshot evidence.
+- [ ] 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.
+
 ## Manual authoring
 
 For a complete editable definition, copy the shipped support example into a new directory from
@@ -233,8 +302,8 @@ and a non-zero exit status.
 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:
+Open Connector is a separately operated service that owns account connections, credentials, and
+its public action runtime. Its implementation is not included in this repository. Configure its endpoint:
 
 ```bash
 export SCHIFT_KS_OPEN_CONNECTOR_URL=http://127.0.0.1:3000
@@ -291,7 +360,7 @@ Start the same application as a loopback service:
 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
+npx --no-install schift-ks serve --host 127.0.0.1 --port 8787
 ```
 
 Routes:

package/dist/context-pack.js

@@ -4120,6 +4120,10 @@ var SearchProviderSchema = exports_external.object({
   kind: exports_external.literal("schift_search"),
   indexRef: KnowledgeScopeIdentifierSchema
 }).strict();
+var LocalDocumentsProviderSchema = exports_external.object({
+  kind: exports_external.literal("local_documents"),
+  indexRef: KnowledgeScopeIdentifierSchema
+}).strict();
 var WebProviderSchema = exports_external.object({
   kind: exports_external.literal("web_search"),
   provider: exports_external.enum(["customer", "schift"])
@@ -4128,6 +4132,7 @@ var QueryProviderSchema = exports_external.discriminatedUnion("kind", [
   RecordsProviderSchema,
   ConnectorProviderSchema,
   SearchProviderSchema,
+  LocalDocumentsProviderSchema,
   WebProviderSchema
 ]).readonly();
 var QueryCapabilitySchema = exports_external.object({
@@ -4236,6 +4241,7 @@ var CandidateProviderEvidenceSchema = exports_external.discriminatedUnion("kind"
     auditPersisted: exports_external.boolean()
   }).strict(),
   SearchProviderSchema,
+  LocalDocumentsProviderSchema,
   WebProviderSchema
 ]).readonly();
 var CandidateEnvelopeSchema = exports_external.object({
@@ -4337,6 +4343,7 @@ var bindingMatchesCapability = (binding, capability) => {
     case "open_connector_action":
       return binding.providerRef === capability.provider.actionId && binding.connectorRef === capability.provider.connectorRef;
     case "schift_search":
+    case "local_documents":
       return binding.providerRef === capability.provider.indexRef && binding.connectorRef === undefined;
     case "web_search":
       return binding.providerRef === capability.provider.provider && binding.connectorRef === undefined;
@@ -4480,6 +4487,10 @@ var ProviderEvidenceSchema = exports_external.discriminatedUnion("kind", [
     kind: exports_external.literal("schift_search"),
     indexRef: KnowledgeScopeIdentifierSchema
   }).strict(),
+  exports_external.object({
+    kind: exports_external.literal("local_documents"),
+    indexRef: KnowledgeScopeIdentifierSchema
+  }).strict(),
   exports_external.object({
     kind: exports_external.literal("web_search"),
     provider: exports_external.enum(["customer", "schift"])
@@ -4638,6 +4649,8 @@ var providerEvidenceDenial = (capability, binding, candidate) => {
       return evidence.auditPersisted ? undefined : "connector_audit_missing";
     case "schift_search":
       return evidence.kind === "schift_search" && evidence.indexRef === capability.provider.indexRef ? undefined : "provider_evidence_mismatch";
+    case "local_documents":
+      return evidence.kind === "local_documents" && evidence.indexRef === capability.provider.indexRef ? undefined : "provider_evidence_mismatch";
     case "web_search":
       return evidence.kind === "web_search" && evidence.provider === capability.provider.provider ? undefined : "provider_evidence_mismatch";
   }