From 32b8f4ed74ca68caa112f1e05b2bc6fc36586df6 Mon Sep 17 00:00:00 2001 From: "Jason Lee (Titan Zero)" Date: Sun, 4 Oct 2026 14:14:18 +1100 Subject: [PATCH 1/2] docs: make AI portfolio workflow reproducible --- .../import-commerce-multi-vertical.yml | 100 ------------------ .github/workflows/verify.yml | 11 ++ .gitignore | 7 ++ README.md | 23 ++-- docs/AI_ENGINEERING.md | 71 +++++++++++++ package-lock.json | 33 ++++++ package.json | 7 ++ 7 files changed, 141 insertions(+), 111 deletions(-) delete mode 100644 .github/workflows/import-commerce-multi-vertical.yml create mode 100644 docs/AI_ENGINEERING.md create mode 100644 package-lock.json diff --git a/.github/workflows/import-commerce-multi-vertical.yml b/.github/workflows/import-commerce-multi-vertical.yml deleted file mode 100644 index 7fb91d7..0000000 --- a/.github/workflows/import-commerce-multi-vertical.yml +++ /dev/null @@ -1,100 +0,0 @@ -name: Import Commerce and Multi-Vertical Template Pack - -on: - pull_request: - branches: [main] - types: [opened, synchronize, reopened] - workflow_dispatch: - -permissions: - contents: write - -concurrency: - group: import-commerce-${{ github.event.pull_request.head.ref || github.ref_name }} - cancel-in-progress: false - -jobs: - import: - if: >- - ${{ - (github.event_name == 'workflow_dispatch' && github.ref_name == 'feature/full-engine-template-upgrade') || - (github.event_name == 'pull_request' && github.event.pull_request.head.ref == 'feature/full-engine-template-upgrade') - }} - runs-on: ubuntu-latest - steps: - - name: Check out feature branch - uses: actions/checkout@v4 - with: - ref: feature/full-engine-template-upgrade - fetch-depth: 0 - persist-credentials: true - - - name: Detect completed import - id: state - shell: bash - run: | - if [[ -f reports/workcore-compatibility.json ]] && php -r '$r=json_decode(file_get_contents("reports/workcore-compatibility.json"), true); exit(($r["summary"]["total_templates"] ?? 0) === 38 ? 0 : 1);'; then - echo "complete=true" >> "$GITHUB_OUTPUT" - else - echo "complete=false" >> "$GITHUB_OUTPUT" - fi - - - name: Download checksum-pinned source - if: steps.state.outputs.complete != 'true' - shell: bash - env: - SOURCE_URL: https://interaction-engine-source-v3.miniup.app/interaction-engine-source.tar.gz - SOURCE_SHA256: d8f0bca52e54d40981ee7a9a345ff04edf56f5d75ba7b418995cb2dfb2fe11e1 - run: | - set -euo pipefail - archive=/tmp/interaction-engine-source.tar.gz - unpacked=/tmp/interaction-engine-source - rm -rf "$archive" "$unpacked" - mkdir -p "$unpacked" - curl --fail --location --silent --show-error --retry 3 --retry-all-errors "$SOURCE_URL" --output "$archive" - actual="$(sha256sum "$archive" | awk '{print $1}')" - test "$actual" = "$SOURCE_SHA256" - tar -tzf "$archive" >/tmp/archive-list.txt - tar -xzf "$archive" -C "$unpacked" - package_root='' - while IFS= read -r composer_file; do - candidate="$(dirname "$composer_file")" - if [[ -d "$candidate/src" && -d "$candidate/wizards" && -d "$candidate/templates" && -f "$candidate/bin/verify.php" ]]; then - package_root="$candidate" - break - fi - done < <(find "$unpacked" -type f -name composer.json | sort) - test -n "$package_root" - rsync -a --delete \ - --exclude='.git/' \ - --exclude='.github/' \ - "$package_root/" ./ - - - name: Verify imported source - if: steps.state.outputs.complete != 'true' - shell: bash - run: | - set -euo pipefail - php bin/verify.php - php_count=0 - while IFS= read -r -d '' file; do php -l "$file" >/dev/null; php_count=$((php_count+1)); done < <(find src tests bin routes config database -type f -name '*.php' -print0 2>/dev/null) - json_count=0 - while IFS= read -r -d '' file; do php -r 'json_decode(file_get_contents($argv[1]), true, 512, JSON_THROW_ON_ERROR);' "$file"; json_count=$((json_count+1)); done < <(find wizards templates resources config reports -type f -name '*.json' -print0 2>/dev/null) - test "$php_count" -eq 336 - test "$json_count" -eq 69 - php -r '$r=json_decode(file_get_contents("reports/workcore-compatibility.json"), true, 512, JSON_THROW_ON_ERROR); exit(($r["summary"]["total_templates"] ?? 0) === 38 && ($r["summary"]["ready_templates"] ?? 0) === 29 && ($r["summary"]["draft_templates"] ?? 0) === 9 ? 0 : 1);' - - - name: Commit verified source - if: steps.state.outputs.complete != 'true' - shell: bash - run: | - set -euo pipefail - git config user.name "github-actions[bot]" - git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git add -A - if git diff --cached --quiet; then - echo "No changes to commit." - exit 0 - fi - git commit -m "feat: add commerce and multi-vertical template pack" - git push origin HEAD:feature/full-engine-template-upgrade diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml index ba9c089..b0c0579 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -22,6 +22,16 @@ jobs: - name: Check out source uses: actions/checkout@v4 + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + + - name: Install offline companion toolchain + shell: bash + run: npm ci + - name: Run complete engine verification shell: bash run: php bin/verify.php @@ -48,3 +58,4 @@ jobs: php -r 'json_decode(file_get_contents($argv[1]), true, 512, JSON_THROW_ON_ERROR);' "$file" done echo "JSON valid: ${#json_files[@]} files" + diff --git a/.gitignore b/.gitignore index 2c178a0..9204660 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,9 @@ .worktrees/ +node_modules/ +coverage/ +.phpunit.result.cache +.env +.env.* +!.env.example + diff --git a/README.md b/README.md index 14c9b95..a2f53e6 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Titan Interaction Runtime — GOVERNED WORKFLOWS · ONLINE + OFFLINE](docs/images/portfolio-banner.svg) +![Titan Interaction Runtime - GOVERNED WORKFLOWS � ONLINE + OFFLINE](docs/images/portfolio-banner.svg)
@@ -84,12 +84,11 @@ The module is intended for a compatible Laravel host. Verify the host version, d ```bash composer install -composer test -npm install -npm test +npm ci +php bin/verify.php ``` -The repository defines Composer and npm test scripts. A prior cumulative build report records standalone syntax, engine-pair, schema, workflow, offline encryption, online command-dispatch, and TypeScript checks. Those historical results are not a substitute for rerunning tests on the current commit or validating a destination host. +`php bin/verify.php` runs the PHP suites and the TypeScript offline-companion tests. The workflow installs the declared TypeScript toolchain before invoking the same verifier, so a clean checkout does not depend on a globally installed compiler. A prior cumulative build report records historical checks; it is not a substitute for rerunning tests on the current commit or validating a destination host. ## Integration requirements @@ -105,11 +104,13 @@ The host business system remains the authority for operational mutations. ## Repository map -- `interactions/`, `wizards/`, `templates/` — interaction and workflow definitions -- `resources/ts/` — device-side offline companion -- `resources/openapi.yaml` — API contract -- `tests/` — runtime and workflow checks -- `docs/`, `reports/` — architecture and verification evidence +- `interactions/`, `wizards/`, `templates/` - interaction and workflow definitions +- `resources/ts/` - device-side offline companion +- `resources/openapi.yaml` - API contract +- `tests/` - runtime and workflow checks +- `docs/`, `reports/` - architecture and verification evidence + +The AI and agent-oriented implementation map is in [`docs/AI_ENGINEERING.md`](docs/AI_ENGINEERING.md). It distinguishes deterministic heuristics, optional cloud-model integration, policy enforcement and host-boundary work from claims the repository does not make. ## Security principles @@ -146,4 +147,4 @@ The Composer package declares a proprietary license. Obtain the appropriate righ ## Banner A checked-in project-specific banner is displayed above. - + diff --git a/docs/AI_ENGINEERING.md b/docs/AI_ENGINEERING.md new file mode 100644 index 0000000..53897dc --- /dev/null +++ b/docs/AI_ENGINEERING.md @@ -0,0 +1,71 @@ +# AI engineering map + +Titan Zero Interaction Engine is an executable workflow and governance foundation with deterministic local intelligence and an optional cloud-model adapter. It is not presented as a trained model, a local LLM, or an autonomous agent that can grant itself authority. + +## The problem this repository addresses + +Business interfaces often stop at intent recognition: they can suggest an action, but the path from suggestion to a durable business mutation is left implicit. This repository makes that path explicit and replayable, including tenant and actor context, approval, evidence, idempotency and offline recovery. + +The central design rule is: + +```text +understanding -> recommendation -> human decision / approval -> governed command -> host outcome +``` + +An intent or prediction never becomes permission by itself. + +## Runtime path + +1. `LocalBrain::process()` calls the PHP `LocalLanguageEngine` for deterministic intent and entity extraction. +2. `HybridReasoner` applies registered rules and lowers confidence when required context is missing. `DecisionTreeEngine` provides a separate schema-driven branch evaluator. +3. `BehavioralMemory`, `TemporalIntelligence` and `PredictiveCompletionEngine` provide suggestions from confirmed local history. `confirmAction()` is the point at which an observed user action can become behavioural evidence. +4. `UniversalWizardEngine` validates a structured workflow and `CommandMapper` creates a capability command with tenant, actor, device, correlation and idempotency metadata. +5. `PolicyEngine` evaluates the command against a `CapabilityPolicy`. It can enforce human-only actions, signed approval, delegated scopes, numeric limits, fresh authentication and tenant boundaries. +6. `CommandBus` dispatches only registered capabilities to the host-facing adapter. `WorkCoreAdapter` translates the approved command; the host business system remains the mutation authority. +7. Offline devices persist encrypted drafts and commands through the TypeScript IndexedDB companion. `/api/interaction/offline-commands` rechecks tenant, idempotency and policy during replay. +8. Cognitive events connect observations, recommendations, user decisions, commands and outcomes so later learning is based on evidence rather than unconfirmed suggestions. + +## Implemented capability map + +| Capability | Implementation | What is actually implemented | +| --- | --- | --- | +| Local language understanding | `src/LocalIntelligence/Language/LocalLanguageEngine.php`, `resources/ts/offline/local-language.ts` | Pattern matching for business intents plus lightweight extraction of customers, services, dates, times, addresses and amounts. | +| Local reasoning | `src/LocalIntelligence/Reasoning/HybridReasoner.php`, `src/LocalIntelligence/Decision/DecisionTreeEngine.php` | Rule-adjusted confidence, evidence, alternatives and clarification decisions; no claim of statistical calibration. | +| Memory and prediction | `src/LocalIntelligence/Memory/BehavioralMemory.php`, `TemporalIntelligence.php`, `PredictiveCompletionEngine.php` | Confirmed action transitions, temporal suggestions and persisted local-memory hooks. Recommendations do not mutate host state. | +| Retrieval and vectors | `src/Engines/AIInfrastructure/Implementations/{EmbeddingEngine,RetrievalEngine,VectorSearchEngine}.php` | Hash-based fixed-size vectors, token-overlap retrieval and in-memory cosine search. These are deterministic indexing baselines, not trained semantic embeddings. | +| Evaluation and prompt support | `EvaluationEngine.php`, `PromptEngine.php`, `PromptOptimizationEngine.php` | Word-overlap scoring and rule-based prompt cleanup/scoring. These are transparent heuristics, not model-quality benchmarks. | +| Tool/function dispatch | `ToolCallingEngine.php`, `FunctionCallingEngine.php`, `CapabilityRegistry.php` | Explicit name-to-callable registries. There is no hidden model loop or unrestricted code execution. | +| Optional cloud AI | `src/AI/OpenAIService.php`, `src/Resolver/Resolvers/AIResolver.php` | Optional OpenAI-backed question resolution when enabled and configured. `NullAIService` fails closed when cloud AI is disabled. Cloud output does not bypass policy or command dispatch. | +| Authority and safety | `src/Policy/PolicyEngine.php`, `src/Authority/*`, `src/Command/CommandBus.php` | Default-deny capability decisions, approval signatures, role/scope/limit checks, tenant checks and policy callbacks before execution. | +| Evidence lineage | `src/Cognition/*`, `src/Events/*`, `src/Http/Controllers/CognitiveEventController.php` | Tenant-scoped cognitive events and outcome links for audit and later learning. | +| Agent-oriented building blocks | `src/Engines/{Planning,Executive,Cognitive,Memory,Learning}/*` | Contract-driven deterministic planning, routing, decision, memory and learning primitives. The 80-engine library is a replaceable baseline library, not 80 trained agents or models. | + +## Engineering tradeoffs + +- Local heuristics keep supported interactions usable without network access and are easy to inspect, test and replay, but they do not understand arbitrary language like a general-purpose model. +- The cloud adapter can improve open-ended question resolution, but it is opt-in, requires a host credential and is deliberately outside the authority boundary. +- Host adapters preserve the destination system's domain rules instead of duplicating them here; this makes the package portable, but connected-host readiness cannot be proven from this repository alone. +- Offline replay is conservative: unsynchronised records remain available for retry or resolution, and replayed commands are subject to the same policy checks as online commands. +- The 80-engine library favours stable contracts and deterministic defaults. Several implementations are intentionally baseline strategies behind interfaces, not production claims about model quality or scale. + +## Evidence and reproducible checks + +From the current repository tree: + +- `tests/run.php` covers core runtime, policy, local-intelligence, offline and host-mapping behaviour. +- `tests/template_catalogue_run.php`, `tests/assurance_workflows_run.php` and `tests/commerce_vertical_workflows_run.php` cover the executable/draft catalogue boundary and workflow governance. +- `tests/ts/offline.test.js` covers encrypted outbox round trips, local language extraction, sync conflicts and cognitive-event replay. +- `scripts/authority-policy-eval.php` runs 31 fixed policy scenarios; the committed report is `eval-results/authority-policy-latest.md`. +- `.github/workflows/verify.yml` runs `php bin/verify.php`, PHP syntax checks and JSON validation after installing the declared Node.js/TypeScript toolchain. + +Run the package checks with: + +```bash +composer install +npm ci +php bin/verify.php +``` + +The repository currently records package-level evidence only. `reports/workcore-compatibility.json` intentionally reports zero connected-host-verified templates; deployment-specific models, permissions, migrations, queues, browser integration, provider integration and load behaviour remain host integration work. + + diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..fa4643d --- /dev/null +++ b/package-lock.json @@ -0,0 +1,33 @@ +{ + "name": "@titanzero/interaction-engine-offline", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@titanzero/interaction-engine-offline", + "version": "1.0.0", + "devDependencies": { + "typescript": "^5.7.0" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + } + } +} + diff --git a/package.json b/package.json index f522bd4..6f6dfb1 100644 --- a/package.json +++ b/package.json @@ -4,9 +4,16 @@ "private": true, "description": "Device-side offline companion for the Titan Zero Interaction Engine", "type": "commonjs", + "engines": { + "node": ">=20" + }, "scripts": { "build": "tsc -p tsconfig.json", "test": "npm run build && node --test tests/ts/*.test.js", "verify": "npm test" + }, + "devDependencies": { + "typescript": "^5.7.0" } } + From 5081ff2d5e6818899b5e57c8778fda0674797c43 Mon Sep 17 00:00:00 2001 From: "Jason Lee (Titan Zero)" Date: Sun, 4 Oct 2026 14:20:57 +1100 Subject: [PATCH 2/2] fix: preserve portfolio documentation encoding --- .github/workflows/verify.yml | 2 +- .gitignore | 2 +- README.md | 14 +++++++------- docs/AI_ENGINEERING.md | 2 +- package-lock.json | 2 +- package.json | 2 +- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml index b0c0579..6c9ba30 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -58,4 +58,4 @@ jobs: php -r 'json_decode(file_get_contents($argv[1]), true, 512, JSON_THROW_ON_ERROR);' "$file" done echo "JSON valid: ${#json_files[@]} files" - + diff --git a/.gitignore b/.gitignore index 9204660..59f1727 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,4 @@ coverage/ .env .env.* !.env.example - + diff --git a/README.md b/README.md index a2f53e6..82f61d9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Titan Interaction Runtime - GOVERNED WORKFLOWS � ONLINE + OFFLINE](docs/images/portfolio-banner.svg) +![Titan Interaction Runtime — GOVERNED WORKFLOWS · ONLINE + OFFLINE](docs/images/portfolio-banner.svg)
@@ -104,11 +104,11 @@ The host business system remains the authority for operational mutations. ## Repository map -- `interactions/`, `wizards/`, `templates/` - interaction and workflow definitions -- `resources/ts/` - device-side offline companion -- `resources/openapi.yaml` - API contract -- `tests/` - runtime and workflow checks -- `docs/`, `reports/` - architecture and verification evidence +- `interactions/`, `wizards/`, `templates/` — interaction and workflow definitions +- `resources/ts/` — device-side offline companion +- `resources/openapi.yaml` — API contract +- `tests/` — runtime and workflow checks +- `docs/`, `reports/` — architecture and verification evidence The AI and agent-oriented implementation map is in [`docs/AI_ENGINEERING.md`](docs/AI_ENGINEERING.md). It distinguishes deterministic heuristics, optional cloud-model integration, policy enforcement and host-boundary work from claims the repository does not make. @@ -147,4 +147,4 @@ The Composer package declares a proprietary license. Obtain the appropriate righ ## Banner A checked-in project-specific banner is displayed above. - + diff --git a/docs/AI_ENGINEERING.md b/docs/AI_ENGINEERING.md index 53897dc..56b726e 100644 --- a/docs/AI_ENGINEERING.md +++ b/docs/AI_ENGINEERING.md @@ -68,4 +68,4 @@ php bin/verify.php The repository currently records package-level evidence only. `reports/workcore-compatibility.json` intentionally reports zero connected-host-verified templates; deployment-specific models, permissions, migrations, queues, browser integration, provider integration and load behaviour remain host integration work. - + diff --git a/package-lock.json b/package-lock.json index fa4643d..836ba31 100644 --- a/package-lock.json +++ b/package-lock.json @@ -30,4 +30,4 @@ } } } - + diff --git a/package.json b/package.json index 6f6dfb1..c880dea 100644 --- a/package.json +++ b/package.json @@ -16,4 +16,4 @@ "typescript": "^5.7.0" } } - +