@weftlet/toolkit 0.0.0-stage → 0.1.1

package/docs/licenses/REVIEW.md

@@ -0,0 +1,16 @@
+# Scoped dependency license review
+
+The RDF dependency tree introduced three expressions outside the original generator allowlist.
+`reviewed-licenses.json` pins these reviews to exact package versions and notice hashes.
+Unrecognized future versions/expressions still fail the check.
+
+- `spark-md5@3.0.2`: upstream package metadata and README offer MIT as an alternative.
+  The npm archive omits `LICENSE2`; the retained MIT notice was retrieved from the peeled
+  `v3.0.2` source commit `9315385868fe11076674d4ddd763005319a462a7`, path `LICENSE2`.
+- `lru-cache@11.5.3`: the installed `LICENSE.md` grants copyright/patent permissions and
+  requires the license text or link. Its complete Blue Oak 1.0.0 text is retained.
+- `negotiate@1.0.1`: metadata says FreeBSD; the installed `negotiate.js` header contains
+  two-clause BSD permissions, copyright and disclaimer. That notice is retained.
+
+These selections support local development and preserve redistribution notices. They do not
+authorize package publication or waive final export review.

package/docs/licenses/lru-cache-11.5.3-BlueOak.md

@@ -0,0 +1,55 @@
+# Blue Oak Model License
+
+Version 1.0.0
+
+## Purpose
+
+This license gives everyone as much permission to work with
+this software as possible, while protecting contributors
+from liability.
+
+## Acceptance
+
+In order to receive this license, you must agree to its
+rules.  The rules of this license are both obligations
+under that agreement and conditions to your license.
+You must not do anything with this software that triggers
+a rule that you cannot or will not follow.
+
+## Copyright
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe that contributor's
+copyright in it.
+
+## Notices
+
+You must ensure that everyone who gets a copy of
+any part of this software from you, with or without
+changes, also gets the text of this license or a link to
+<https://blueoakcouncil.org/license/1.0.0>.
+
+## Excuse
+
+If anyone notifies you in writing that you have not
+complied with [Notices](#notices), you can keep your
+license by taking all practical steps to comply within 30
+days after the notice.  If you do not do so, your license
+ends immediately.
+
+## Patent
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe any patent claims
+they can license or become able to license.
+
+## Reliability
+
+No contributor can revoke this license.
+
+## No Liability
+
+***As far as the law allows, this software comes as is,
+without any warranty or condition, and no contributor
+will be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim.***

package/docs/licenses/negotiate-1.0.1-BSD.txt

@@ -0,0 +1,22 @@
+Copyright 2010 Gary Court. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY GARY COURT ``AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL GARY COURT OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ 

package/docs/licenses/spark-md5-3.0.2-MIT.txt

@@ -0,0 +1,7 @@
+Copyright (c) 2015 André Cruz <amdfcruz@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/examples/generic-typescript/context-graph.config.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": 1,
+  "repositoryRoot": ".",
+  "repositoryId": "example/generic-typescript",
+  "namespace": "https://example.test/context/",
+  "semanticSources": [
+    "docs"
+  ],
+  "codeRoots": [
+    "src"
+  ],
+  "contractPatterns": [],
+  "evidenceRoots": [
+    "test"
+  ],
+  "semantic": {
+    "provider": "codex-cli",
+    "model": "gpt-6-astra",
+    "reasoningEffort": "medium",
+    "promptVersion": "generic-semantic-v3",
+    "extractorVersion": "1.1.0",
+    "adapterVersion": "1.1.0",
+    "ontologyVersion": "1.1.0",
+    "minimumConfidence": 0.7,
+    "failOnUnresolved": true,
+    "concurrency": 1
+  },
+  "scip": {
+    "version": "0.4.0",
+    "command": "bundled-scip-typescript",
+    "args": [
+      "index",
+      "--no-global-caches",
+      "--infer-tsconfig"
+    ]
+  },
+  "ontology": {
+    "backend": "rdf",
+    "toolVersion": "rdf-record-v1"
+  },
+  "runtimeEvidence": [],
+  "storagePath": ".context-graph",
+  "x-extraction-modifications": "Portable example model profile; runtime evidence is opt-in.",
+  "approvedIntentSources": [
+    "docs/search-capability.md"
+  ]
+}

package/examples/generic-typescript/context-graph.oml.config.json

@@ -0,0 +1,49 @@
+{
+  "schemaVersion": 1,
+  "repositoryRoot": ".",
+  "repositoryId": "example/generic-typescript",
+  "namespace": "https://example.test/context/",
+  "semanticSources": [
+    "docs"
+  ],
+  "codeRoots": [
+    "src"
+  ],
+  "contractPatterns": [],
+  "evidenceRoots": [
+    "test"
+  ],
+  "semantic": {
+    "provider": "codex-cli",
+    "model": "gpt-6-astra",
+    "reasoningEffort": "medium",
+    "promptVersion": "generic-semantic-v3",
+    "extractorVersion": "1.1.0",
+    "adapterVersion": "1.1.0",
+    "ontologyVersion": "1.1.0",
+    "minimumConfidence": 0.7,
+    "failOnUnresolved": true,
+    "concurrency": 1
+  },
+  "scip": {
+    "version": "0.4.0",
+    "command": "bundled-scip-typescript",
+    "args": [
+      "index",
+      "--no-global-caches",
+      "--infer-tsconfig"
+    ]
+  },
+  "ontology": {
+    "toolVersion": "oml2owl-gradle-2.13.1",
+    "containerImage": "gradle:8.10.2-jdk21@sha256:963d59f7f22767da4efbcf46b661361b61af5fb88b0309da1071c4234c647eba",
+    "projectPath": "ontology",
+    "backend": "opencaesar"
+  },
+  "runtimeEvidence": [],
+  "storagePath": ".context-graph",
+  "x-extraction-modifications": "Portable example model profile; runtime evidence is opt-in.",
+  "approvedIntentSources": [
+    "docs/search-capability.md"
+  ]
+}

package/examples/generic-typescript/docs/search-capability.md

@@ -0,0 +1,14 @@
+semantic-id: capability:document-search
+
+# Document Search
+
+The stable identifiers in this capability are:
+
+- `capability:document-search` for the search capability.
+- `component:query-service` for the query service.
+- `contract:document-repository` for the document repository contract.
+- `contract:search` for the search contract.
+- `evidence:test-search-test-ts` for `test/search.test.ts`.
+
+The search capability is implemented by the query service. The service consumes the document
+repository contract, and the search contract is verified by `test/search.test.ts`.

package/examples/generic-typescript/ontology/build.gradle

@@ -0,0 +1,38 @@
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'io.opencaesar.oml:oml-merge-gradle:2.13.0'
+        classpath 'io.opencaesar.adapters:oml2owl-gradle:2.13.1'
+    }
+}
+
+apply plugin: 'base'
+apply plugin: 'oml'
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    oml 'io.opencaesar.ontologies:core-vocabularies:5.1.0'
+}
+
+task downloadDependencies(type: io.opencaesar.oml.merge.OmlMergeTask, dependsOn: configurations.oml) {
+    inputZipPaths = configurations.oml.files
+    outputCatalogFolder = file('build/oml')
+}
+
+task oml2owl(type: io.opencaesar.oml2owl.Oml2OwlTask, dependsOn: downloadDependencies) {
+    inputCatalogPath = file('catalog.xml')
+    rootOntologyIri = 'https://context-graph.dev/generated/snapshot'
+    outputCatalogPath = file('build/rdf/catalog.xml')
+    outputFileExtension = 'ttl'
+    generateRules = true
+    omlAnnotations = 'generate'
+}
+
+tasks.named('build') {
+    dependsOn oml2owl
+}

package/examples/generic-typescript/ontology/catalog.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0"?>
+<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public">
+  <rewriteURI uriStartString="https://context-graph.dev/" rewritePrefix="src/oml/context-graph.dev/"/>
+  <rewriteURI uriStartString="http://" rewritePrefix="build/oml/"/>
+</catalog>

package/examples/generic-typescript/ontology/settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'generic-context-graph-ontology'

package/examples/generic-typescript/ontology/src/oml/context-graph.dev/core.oml

@@ -0,0 +1,99 @@
+vocabulary <https://context-graph.dev/core#> as cg {
+  extends <http://www.w3.org/2001/XMLSchema#> as xsd
+
+  aspect GraphElement [
+    key hasIdentifier
+  ]
+
+  scalar property hasIdentifier [
+    domain GraphElement
+    range xsd:string
+    functional
+  ]
+
+  concept Project < GraphElement
+  concept ProductCapability < GraphElement
+  concept Workflow < GraphElement
+  concept RuntimeComponent < GraphElement
+  concept APIContract < GraphElement
+  concept EventContract < GraphElement
+  concept QueueContract < GraphElement
+  concept PersistenceModel < GraphElement
+  concept Provider < GraphElement
+  concept Scope < GraphElement
+  concept OwnerDocument < GraphElement
+  concept ValidationArtifact < GraphElement
+  concept ArchitectureInvariant < GraphElement
+  concept DecisionAuthority < GraphElement
+
+  relation realizes [
+    from RuntimeComponent
+    to ProductCapability
+    reverse implementedBy
+  ]
+
+  relation consumes [
+    from RuntimeComponent
+    to GraphElement
+  ]
+
+  relation emits [
+    from RuntimeComponent
+    to GraphElement
+  ]
+
+  relation persistsTo [
+    from RuntimeComponent
+    to PersistenceModel
+  ]
+
+  relation governedBy [
+    from GraphElement
+    to ArchitectureInvariant
+  ]
+
+  relation definedBy [
+    from GraphElement
+    to OwnerDocument
+  ]
+
+  relation verifiedBy [
+    from GraphElement
+    to ValidationArtifact
+  ]
+
+  relation operationallyOwnedBy [
+    from ProductCapability
+    to RuntimeComponent
+  ]
+
+  relation hasDecisionAuthority [
+    from GraphElement
+    to DecisionAuthority
+  ]
+
+  relation routesThrough [
+    from RuntimeComponent
+    to RuntimeComponent
+  ]
+
+  relation authorizedBy [
+    from GraphElement
+    to Scope
+  ]
+
+  relation sourcedFrom [
+    from GraphElement
+    to Provider
+  ]
+
+  relation references [
+    from GraphElement
+    to GraphElement
+  ]
+
+  relation contains [
+    from GraphElement
+    to GraphElement
+  ]
+}

package/examples/generic-typescript/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "generic-context-graph-example",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module"
+}

package/examples/generic-typescript/src/search.ts

@@ -0,0 +1,11 @@
+export interface DocumentRepository {
+  search(query: string): Promise<readonly string[]>;
+}
+
+export class SearchService {
+  constructor(private readonly repository: DocumentRepository) {}
+
+  search(query: string): Promise<readonly string[]> {
+    return this.repository.search(query.trim());
+  }
+}

package/examples/generic-typescript/test/search.test.ts

@@ -0,0 +1,8 @@
+import { expect, it } from 'vitest';
+
+import { SearchService } from '../src/search.js';
+
+it('proves the portable fixture service contract', async () => {
+  const service = new SearchService({ search: async (query) => [query] });
+  await expect(service.search(' context ')).resolves.toEqual(['context']);
+});

package/examples/generic-typescript/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/examples/pipeline/context-graph.config.json

@@ -0,0 +1,49 @@
+{
+  "schemaVersion": 1,
+  "repositoryRoot": ".",
+  "repositoryId": "example/pipeline",
+  "namespace": "https://example.test/context/",
+  "semanticSources": [
+    "docs"
+  ],
+  "codeRoots": [
+    "src"
+  ],
+  "contractPatterns": [
+    "src/contracts/*.ts"
+  ],
+  "evidenceRoots": [
+    "test"
+  ],
+  "semantic": {
+    "provider": "codex-cli",
+    "model": "gpt-6-astra",
+    "reasoningEffort": "medium",
+    "promptVersion": "generic-semantic-v3",
+    "extractorVersion": "1.1.0",
+    "adapterVersion": "1.1.0",
+    "ontologyVersion": "1.1.0",
+    "minimumConfidence": 0.7,
+    "failOnUnresolved": true,
+    "concurrency": 1
+  },
+  "scip": {
+    "version": "0.4.0",
+    "command": "bundled-scip-typescript",
+    "args": [
+      "index",
+      "--no-global-caches",
+      "--infer-tsconfig"
+    ]
+  },
+  "ontology": {
+    "backend": "rdf",
+    "toolVersion": "rdf-record-v1"
+  },
+  "runtimeEvidence": [],
+  "storagePath": ".context-graph",
+  "x-extraction-modifications": "Portable example model profile; runtime evidence is opt-in.",
+  "approvedIntentSources": [
+    "docs/*.md"
+  ]
+}

package/examples/pipeline/docs/admission.md

@@ -0,0 +1,6 @@
+semantic-id: pipeline:admission
+# Admission intent
+Status: approved example policy (fictional product).
+The admission stage is implemented by src/admission.ts.
+The admission stage routes through the planning stage using an asynchronous queue.
+The shared message contract is src/contracts/planning.ts.

package/examples/pipeline/docs/analysis.md

@@ -0,0 +1,6 @@
+semantic-id: pipeline:analysis
+# Analysis intent
+Status: approved example policy (fictional product).
+The analysis stage is implemented by src/analysis.ts.
+The analysis stage routes through the admission stage using an asynchronous queue.
+The shared message contract is src/contracts/admission.ts.

package/examples/pipeline/docs/discovery.md

@@ -0,0 +1,6 @@
+semantic-id: pipeline:discovery
+# Discovery intent
+Status: approved example policy (fictional product).
+The discovery stage is implemented by src/discovery.ts.
+The discovery stage routes through the analysis stage using an asynchronous queue.
+The shared message contract is src/contracts/analysis.ts.

package/examples/pipeline/docs/execution.md

@@ -0,0 +1,6 @@
+semantic-id: pipeline:execution
+# Execution intent
+Status: approved example policy (fictional product).
+The execution stage is implemented by src/execution.ts.
+The execution stage routes through the outcomes stage using an asynchronous queue.
+The shared message contract is src/contracts/outcomes.ts.

package/examples/pipeline/docs/outcomes.md

@@ -0,0 +1,6 @@
+semantic-id: pipeline:outcomes
+# Outcomes intent
+Status: approved example policy (fictional product).
+The outcomes stage is implemented by src/outcomes.ts.
+The outcomes stage routes through the discovery stage using an asynchronous queue.
+The shared message contract is src/contracts/discovery.ts.

package/examples/pipeline/docs/planning.md

@@ -0,0 +1,6 @@
+semantic-id: pipeline:planning
+# Planning intent
+Status: approved example policy (fictional product).
+The planning stage is implemented by src/planning.ts.
+The planning stage routes through the execution stage using an asynchronous queue.
+The shared message contract is src/contracts/execution.ts.

package/examples/pipeline/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "context-graph-pipeline-example",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module"
+}

package/examples/pipeline/src/admission.ts

@@ -0,0 +1,9 @@
+import type { Queue } from './queue.js';
+import type { AdmissionMessage } from './contracts/admission.js';
+import type { PlanningMessage } from './contracts/planning.js';
+
+export function admission(input: Queue<AdmissionMessage>, output: Queue<PlanningMessage>) {
+  input.subscribe(async (message) => {
+    await output.publish({ id: message.id, value: message.value + 1 });
+  });
+}

package/examples/pipeline/src/analysis.ts

@@ -0,0 +1,9 @@
+import type { Queue } from './queue.js';
+import type { AnalysisMessage } from './contracts/analysis.js';
+import type { AdmissionMessage } from './contracts/admission.js';
+
+export function analysis(input: Queue<AnalysisMessage>, output: Queue<AdmissionMessage>) {
+  input.subscribe(async (message) => {
+    await output.publish({ id: message.id, value: message.value + 1 });
+  });
+}

package/examples/pipeline/src/contracts/admission.ts

@@ -0,0 +1 @@
+export interface AdmissionMessage { id: string; value: number }

package/examples/pipeline/src/contracts/analysis.ts

@@ -0,0 +1 @@
+export interface AnalysisMessage { id: string; value: number }

package/examples/pipeline/src/contracts/discovery.ts

@@ -0,0 +1 @@
+export interface DiscoveryMessage { id: string; value: number }

package/examples/pipeline/src/contracts/execution.ts

@@ -0,0 +1 @@
+export interface ExecutionMessage { id: string; value: number }

package/examples/pipeline/src/contracts/outcomes.ts

@@ -0,0 +1 @@
+export interface OutcomesMessage { id: string; value: number }

package/examples/pipeline/src/contracts/planning.ts

@@ -0,0 +1 @@
+export interface PlanningMessage { id: string; value: number }

package/examples/pipeline/src/discovery.ts

@@ -0,0 +1,9 @@
+import type { Queue } from './queue.js';
+import type { DiscoveryMessage } from './contracts/discovery.js';
+import type { AnalysisMessage } from './contracts/analysis.js';
+
+export function discovery(input: Queue<DiscoveryMessage>, output: Queue<AnalysisMessage>) {
+  input.subscribe(async (message) => {
+    await output.publish({ id: message.id, value: message.value + 1 });
+  });
+}

package/examples/pipeline/src/execution.ts

@@ -0,0 +1,9 @@
+import type { Queue } from './queue.js';
+import type { ExecutionMessage } from './contracts/execution.js';
+import type { OutcomesMessage } from './contracts/outcomes.js';
+
+export function execution(input: Queue<ExecutionMessage>, output: Queue<OutcomesMessage>) {
+  input.subscribe(async (message) => {
+    await output.publish({ id: message.id, value: message.value + 1 });
+  });
+}

package/examples/pipeline/src/outcomes.ts

@@ -0,0 +1,9 @@
+import type { Queue } from './queue.js';
+import type { OutcomesMessage } from './contracts/outcomes.js';
+import type { DiscoveryMessage } from './contracts/discovery.js';
+
+export function outcomes(input: Queue<OutcomesMessage>, output: Queue<DiscoveryMessage>) {
+  input.subscribe(async (message) => {
+    await output.publish({ id: message.id, value: message.value + 1 });
+  });
+}

package/examples/pipeline/src/planning.ts

@@ -0,0 +1,9 @@
+import type { Queue } from './queue.js';
+import type { PlanningMessage } from './contracts/planning.js';
+import type { ExecutionMessage } from './contracts/execution.js';
+
+export function planning(input: Queue<PlanningMessage>, output: Queue<ExecutionMessage>) {
+  input.subscribe(async (message) => {
+    await output.publish({ id: message.id, value: message.value + 1 });
+  });
+}

package/examples/pipeline/src/queue.ts

@@ -0,0 +1,12 @@
+export interface Queue<T> {
+  publish(value: T): Promise<void>;
+  subscribe(handler: (value: T) => Promise<void>): void;
+}
+export class MemoryQueue<T> implements Queue<T> {
+  private handlers: ((value: T) => Promise<void>)[] = [];
+  subscribe(handler: (value: T) => Promise<void>) { this.handlers.push(handler); }
+  async publish(value: T) {
+    await Promise.resolve();
+    for (const handler of this.handlers) await handler(value);
+  }
+}

package/examples/pipeline/test/pipeline.test.ts

@@ -0,0 +1,17 @@
+import { MemoryQueue } from '../src/queue.js';
+import { discovery } from '../src/discovery.js';
+import { analysis } from '../src/analysis.js';
+import { admission } from '../src/admission.js';
+import { planning } from '../src/planning.js';
+import { execution } from '../src/execution.js';
+import { outcomes } from '../src/outcomes.js';
+
+export async function verifyPipeline(): Promise<void> {
+  const queues = Array.from({ length: 7 }, () => new MemoryQueue<{ id: string; value: number }>());
+  [discovery, analysis, admission, planning, execution, outcomes].forEach((stage, index) =>
+    stage(queues[index]!, queues[index + 1]!));
+  let observed: number | undefined;
+  queues[6]!.subscribe(async (message) => { observed = message.value; });
+  await queues[0]!.publish({ id: 'public-fixture', value: 0 });
+  if (observed !== 6) throw new Error(`Expected all six asynchronous stages; received ${observed}`);
+}

package/examples/pipeline/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts"
+  ]
+}