@bpmsoftwaresolutions/ai-engine-client 1.0.0-beta.8 → 1.1.0

package/README.md

@@ -10,13 +10,25 @@ No repo clone required. Install the package, point it at the Azure service, and
 npm install @bpmsoftwaresolutions/ai-engine-client
 ```
 
+## Publishing
+
+This package is published automatically from GitHub Actions by `.github/workflows/publish-ai-engine-client.yml`.
+
+The workflow runs on pushes to `main` when files under `packages/ai-engine-client/**` change, and it can also be started manually with `workflow_dispatch`.
+
+Authentication supports either:
+
+- npm trusted publishing
+- a repository secret named `NPM_TOKEN`, `NPM_PUBLISH_TOKEN`, or `NODE_AUTH_TOKEN`
+
 ## Quick Start
 
 ```js
 import { AIEngineClient } from '@bpmsoftwaresolutions/ai-engine-client';
 
 const client = new AIEngineClient({
-  baseUrl: 'https://resume-generator-api.politehill-3458aba1.eastus.azurecontainerapps.io'
+  baseUrl: 'https://55e8b585-6076-4992-a164-a5398899efdb-00-c56xlmp9cuq9.worf.replit.dev',
+  // pass the key via a custom header or interceptor
 });
 
 // Health
@@ -38,13 +50,123 @@ const charter = await client.createProjectCharter({
 
 // Read the resulting project roadmap
 const roadmap = await client.getProjectRoadmap(charter.project_id);
+
+const startup = await client.startSessionGovernance({
+  objective: 'Persist governed assistant turns for the charter project.',
+  allowed_mutation_surfaces: ['src/', 'scripts/'],
+});
+
+const persistedTurn = await client.persistAssistantTurn({
+  project_id: charter.project_id,
+  session_key: startup.session_key,
+  user_request: 'Proceed with the next roadmap slice.',
+  assistant_summary: 'Completed the implementation step and persisted the governed turn.',
+  changed_files: ['src/web/app.py'],
+});
+```
+
+## Integration Notes
+
+### Auth Modes
+
+The package supports two authentication patterns:
+
+1. Bearer-token auth for operator and governed routes.
+2. Compatibility API-key auth for migration-oriented external routes and deployments that still allow shared-key access.
+
+Header behavior is:
+
+- If `accessToken` or `tokenProvider` is configured, the client sends `Authorization: Bearer <token>`.
+- If bearer auth is not configured, the client sends `X-API-Key` when `apiKey` is provided.
+- If bearer auth is not configured and `clientId` is provided, the client also sends `X-Client-Id`.
+- The client always sends `X-Actor-Id` for audit trails unless overridden.
+
+That means this package wraps both operator/governed routes and selected external `/api/v1/*` routes. Pick the auth mode that matches the route family exposed by your deployment.
+
+### Route Families
+
+- Operator and governed routes are methods such as `createProjectCharter`, `getProjectBundle`, `importImplementationPacket`, and the workflow/portfolio/governance APIs.
+- External routes are the methods prefixed with `getExternal*`, `listExternal*`, `downloadExternal*`, plus `startSessionGovernance`, `persistAssistantTurn`, `createExternalAudioRender`, and `getLatestMemoryProjection`.
+
+If your deployment enforces bearer auth on operator routes, API-key-only construction will not work for those methods.
+
+### Text and Binary Downloads
+
+Some methods do not return plain JSON:
+
+- Markdown download helpers return `{ text, contentType, fileName, headers }`.
+- LOGA projection helpers return markdown plus governed projection metadata: `{ text, contentType, headers, logaContract, interactionContract, projectionType, projectionVersion, sourceTruth, sourceVersion, correlationId, refreshPolicy, generatedAt, provenance }`.
+- Binary download helpers return `{ arrayBuffer, contentType, fileName }`.
+
+Examples:
+
+```js
+import fs from 'node:fs';
+
+const markdown = await client.downloadProjectCharterReportMarkdown(projectId);
+console.log(markdown.fileName, markdown.contentType);
+console.log(markdown.text);
+
+const logaRoadmap = await client.getLogaProjectRoadmapProjection(projectId);
+console.log(logaRoadmap.projectionType, logaRoadmap.projectionVersion);
+console.log(logaRoadmap.provenance.sourceTruth, logaRoadmap.correlationId);
+console.log(logaRoadmap.text);
+
+const logaRoadmapItem = await client.getLogaRoadmapItemProjection(projectId, 'execute-scope-1');
+console.log(logaRoadmapItem.projectionType, logaRoadmapItem.provenance.sourceVersion);
+console.log(logaRoadmapItem.text);
+
+const audio = await client.downloadExternalAudioRender(audioRenderRunId);
+await fs.promises.writeFile('render.mp3', Buffer.from(audio.arrayBuffer));
+```
+
+### LOGA Projection Contract
+
+LOGA should use the `getLoga*Projection()` methods for runtime documents. These endpoints are governed AI Engine transformations: durable SQL state is normalized into typed projection models, transformed into versioned structured markdown, and served with provenance, refresh, and action metadata for LOGA to render.
+
+The client exposes the transport metadata from response headers so LOGA can validate the contract before rendering:
+
+- `logaContract`: currently `ai-engine-ui/v1`
+- `interactionContract`: currently `loga-choreography/v1`
+- `projectionType`: for example `operator.project_roadmap`
+- `projectionWorkflow`: currently `loga-document-projection`
+- `projectionVersion`
+- `sourceTruth`: normally `sql`
+- `sourceVersion`
+- `correlationId`
+- `refreshPolicy`
+- `generatedAt`
+- `provenance`: grouped copy of the source/projection/version fields
+
+Example:
+
+```js
+import {
+  AIEngineClient,
+  LOGA_CONTRACT,
+  LOGA_INTERACTION_CONTRACT,
+} from '@bpmsoftwaresolutions/ai-engine-client';
+
+const client = AIEngineClient.fromEnv();
+const projection = await client.getLogaProjectRoadmapProjection(projectId);
+
+if (projection.logaContract !== LOGA_CONTRACT) {
+  throw new Error(`Unsupported LOGA contract: ${projection.logaContract}`);
+}
+
+console.log(projection.interactionContract === LOGA_INTERACTION_CONTRACT);
+renderLogaMarkdown(projection.text, {
+  projectionType: projection.projectionType,
+  provenance: projection.provenance,
+});
 ```
 
 ### fromEnv
 
 ```js
 const client = AIEngineClient.fromEnv();
-// Reads: AI_ENGINE_BASE_URL, AI_ENGINE_API_KEY, AI_ENGINE_ACTOR_ID
+// Reads: AI_ENGINE_BASE_URL, AI_ENGINE_ACCESS_TOKEN, AI_ENGINE_API_KEY,
+// AI_ENGINE_CLIENT_ID, AI_ENGINE_ACTOR_ID
 ```
 
 ---
@@ -54,11 +176,156 @@ const client = AIEngineClient.fromEnv();
 | Option | Type | Description |
 |---|---|---|
 | `baseUrl` | string | **Required.** Base URL of the AI Engine service. |
-| `apiKey` | string | Bearer token sent as `Authorization` header. |
+| `accessToken` | string | Static bearer token sent as `Authorization`. |
+| `tokenProvider` | function | Async callback that returns a bearer token string or `{ token }` / `{ accessToken }` per request. |
+| `apiKey` | string | Compatibility API key sent as `X-API-Key` when bearer auth is not configured. |
+| `clientId` | string | Compatibility client id sent as `X-Client-Id` when bearer auth is not configured. |
 | `actorId` | string | Sent as `X-Actor-Id` for audit trails. Default: `sdk:npm-ai-engine-client`. |
 | `fetchImpl` | function | Custom fetch (Node 18+ built-in used by default). |
 | `timeoutMs` | number | Per-request timeout in ms. Default: 30000. |
 
+### Token Provider
+
+```js
+const client = new AIEngineClient({
+  baseUrl: process.env.AI_ENGINE_BASE_URL,
+  tokenProvider: async () => {
+    const token = await acquireAccessToken();
+    return { token };
+  },
+});
+```
+
+### API Key Compatibility
+
+```js
+const client = new AIEngineClient({
+  baseUrl: process.env.AI_ENGINE_BASE_URL,
+  clientId: process.env.AI_ENGINE_CLIENT_ID,
+  apiKey: process.env.AI_ENGINE_API_KEY,
+});
+```
+
+When `accessToken` or `tokenProvider` is present, the client prefers bearer auth. API key headers are only sent when bearer auth is not configured.
+
+Some deployments accept a shared `X-API-Key` without `X-Client-Id`, while others require both `X-Client-Id` and `X-API-Key` for API-key auth. If your environment uses client-scoped API keys, provide both values.
+
+### Project Chartering Contract
+
+`createProjectCharter()` sends snake_case fields to `POST /api/projects/charter`. The method accepts:
+
+- `projectName`, `objective`
+- `businessContext`, `successCriteria`, `priority`
+- `constraints`, `inScope`, `outOfScope`, `assumptions`
+- `linkedWorkflows`, `linkedWorkflowSlug`
+- `testingStrategy`, `initialContext`
+- `requestedBy`
+- `ensureTaskSurface`, `assignedTo`, `createAcceptanceSubtasks`
+
+The response always includes the charter identifiers:
+
+- `project_id`
+- `workflow_id`
+- `workflow_run_id`
+- `implementation_packet_id`
+- `implementation_packet_key`
+- `status`
+
+If `ensureTaskSurface` is left as `true`, the server also attempts to attach `task_surface` for the active roadmap item. That field is only available when the server can resolve an active implementation item from the project roadmap. If roadmap state is incomplete in the deployment, charter creation can still succeed while `task_surface` is unavailable.
+
+Example:
+
+```js
+const charter = await client.createProjectCharter({
+  projectName: 'Loga Cognitive Interface Cockpit Delivery',
+  objective: 'Deliver the operator cockpit and playback experience.',
+  businessContext: 'Ground the first playback surface in convert-document-to-audio.',
+  linkedWorkflowSlug: 'convert-document-to-audio',
+  ensureTaskSurface: true,
+  createAcceptanceSubtasks: true,
+});
+
+console.log(charter.project_id);
+console.log(charter.implementation_packet_key);
+console.log(charter.task_surface?.active_item?.implementation_item_id ?? null);
+```
+
+### Implementation Packet Import Contract
+
+`importImplementationPacket(body)` expects the engine's `implementation_plan_packet` schema, not an arbitrary roadmap-shaped JSON document.
+
+Minimum required top-level fields:
+
+- `packetType`
+- `packetVersion`
+- `packetId`
+- `title`
+- `phases`
+- `governance.requiredGates`
+
+Minimum required fields for each item:
+
+- `itemKey`
+- `type`
+- `description`
+- `acceptanceChecks`
+
+Allowed packet statuses include `draft`, `approved`, `blocked`, `completed`, and other governed packet lifecycle states. Custom statuses such as `draft-local-artifact` are not valid for import.
+
+Minimal example:
+
+```js
+await client.importImplementationPacket({
+  packetType: 'implementation_plan_packet',
+  packetVersion: '1.0',
+  packetId: 'impl-loga-cockpit-v1',
+  title: 'Loga Cognitive Interface Cockpit Delivery',
+  status: 'draft',
+  governance: {
+    requiredGates: ['intent', 'structure', 'promotion'],
+  },
+  phases: [
+    {
+      phaseKey: 'phase_1_foundation',
+      title: 'Foundation',
+      items: [
+        {
+          itemKey: 'define-cockpit-surface',
+          type: 'ui_slice',
+          description: 'Define the first cockpit delivery slice.',
+          acceptanceChecks: [
+            { text: 'The initial slice is explicitly bounded.' },
+          ],
+        },
+      ],
+    },
+  ],
+});
+```
+
+The package does not auto-convert nested human planning structures like `tasks` and `subtasks` into durable implementation-item tasks. To create persisted task records after import, use `ensureProjectRoadmapTaskSurface()` or `createImplementationTask()`.
+
+A copyable example payload is packaged at `examples/implementation-plan-packet.minimal.json`.
+
+### External Audio Render Example
+
+```js
+const render = await client.createExternalAudioRender({
+  text: '# Weekly Update\n\nThe platform migration is on track.',
+  voice: 'alloy',
+});
+
+const status = await client.getExternalAudioRender(render.audio_render_run_id);
+const audio = await client.downloadExternalAudioRender(render.audio_render_run_id);
+```
+
+### External Workflow Artifact Example
+
+```js
+const manifest = await client.listExternalWorkflowRunArtifacts('run-123');
+const packet = await client.downloadExternalWorkflowRunArtifact('run-123', 'package_payload');
+```
+
 ---
 
 ## Methods
@@ -67,6 +334,18 @@ const client = AIEngineClient.fromEnv();
 | Method | Description |
 |---|---|
 | `ping()` | Health check + current workflow name/status. |
+| `startSessionGovernance(body)` | Start a governed external session and return the `session_key` required for mutation-capable assistant turns. |
+| `persistAssistantTurn(body)` | Persist an assistant turn to durable SQL through the API and return refreshed status projections. |
+| `createExternalAudioRender({ text, voice, model, speed, file })` | Create a client-scoped external audio render using inline text or multipart upload. |
+| `getExternalAudioRender(audioRenderRunId)` | Read external audio render status for the authenticated client. |
+| `downloadExternalAudioRender(audioRenderRunId)` | Download the rendered MP3 artifact for the authenticated client. |
+| `listExternalWorkflowRunArtifacts(workflowRunId)` | List signed external artifact descriptors for an authenticated external workflow run. |
+| `downloadExternalWorkflowRunArtifact(workflowRunId, artifactType)` | Download one authenticated external workflow-run artifact by type. |
+| `getExternalProjectStatus(projectId)` | API-key-compatible project status read through the external `/api/v1` boundary. |
+| `getExternalProjectRoadmapSummary(projectId)` | API-key-compatible roadmap summary read through the external `/api/v1` boundary. |
+| `getExternalProjectRoadmapActiveItem(projectId)` | API-key-compatible active roadmap item read through the external `/api/v1` boundary. |
+| `listExternalProjectOpenTasks(projectId)` | API-key-compatible open task read through the external `/api/v1` boundary. |
+| `getExternalProjectStatusBundle(projectId)` | One-call API-key-compatible bundle for project status, roadmap summary, active item, and open tasks. |
 
 ### Operator Status
 | Method | Description |
@@ -75,7 +354,7 @@ const client = AIEngineClient.fromEnv();
 | `currentArchitectureIntegrityStatus()` | Architecture integrity scan results. |
 | `currentSecurityGovernanceStatus({ environment, topN })` | Security governance findings. |
 | `currentCodebaseShapeStatus()` | Codebase shape analysis. |
-| `getLatestMemoryProjection()` | Current SQL memory projection (startup hydration source). |
+| `getLatestMemoryProjection()` | Current SQL memory projection (startup hydration source) through the general external `/api/v1/latest-memory-projection` route. |
 | `currentProjectStatus({ projectId })` | Current project status projection from SQL memory. |
 | `createDatabaseBackup({ databaseName, outputName, noWait })` | Start a database backup using server-owned Azure backup defaults. |
 | `listDatabaseBackups({ prefix, limit })` | List recent backups from the server-owned backup storage location. |
@@ -93,6 +372,18 @@ Low-level compatibility methods:
 | `listAzureSqlBacpacBackups({ storageAccount, container, ... })` | List BACPAC exports through the legacy infra-shaped operator API. |
 | `listAzureSqlBacpacBackupOperations({ databaseName, resourceGroup, serverName, ... })` | List Azure SQL operations through the legacy infra-shaped operator API. |
 
+### LOGA Projections
+| Method | Endpoint | Description |
+|---|---|---|
+| `getLogaOperatorHomeProjection()` | `GET /api/operator/projections/home` | Governed operator home runtime markdown document. |
+| `getLogaProjectCatalogProjection()` | `GET /api/operator/projections/project-catalog` | Governed project catalog runtime markdown document. |
+| `getLogaProjectRoadmapProjection(projectId)` | `GET /api/operator/projections/projects/:projectId/roadmap.md` | Governed project roadmap runtime markdown document. |
+| `getLogaRoadmapItemProjection(projectId, itemKey)` | `GET /api/operator/projections/projects/:projectId/roadmap/items/:itemKey` | Governed roadmap item runtime markdown document with item-level navigation, related documents, actions, and evidence. |
+| `getLogaWorkflowRunProjection(workflowRunId)` | `GET /api/operator/projections/workflow-runs/:workflowRunId` | Governed workflow run runtime markdown document. |
+| `getLogaEvidencePacketProjection(packetKey)` | `GET /api/operator/projections/evidence-packets/:packetKey` | Governed evidence packet runtime markdown document. |
+
+These methods return markdown as `text` and expose projection headers as top-level fields plus `provenance`. LOGA should render the markdown emitted by AI Engine and use these metadata fields for contract validation, refresh behavior, evidence display, and action choreography.
+
 ### Retrieval Wrapper
 | Method | Description |
 |---|---|
@@ -169,6 +460,7 @@ Low-level compatibility methods:
 | `getWorkflowRun(workflowRunId)` | Get run detail. |
 | `listWorkflowArtifacts(workflowRunId)` | List run artifacts. |
 | `getWorkflowRunSubstrate(workflowRunId)` | Get run substrate (sessions, turns). |
+| `getWorkflowPlayback(workflowRunId)` | Get the playback-lite workflow timeline view derived from step runs and artifacts. |
 | `resumeWorkflowRun(workflowRunId, body)` | Resume a paused run. |
 | `listRecentInspectorRuns({ limit })` | List recent runs via inspector. |
 | `inspectWorkflowRun(workflowRunId)` | Full inspector view of a run. |
@@ -219,6 +511,9 @@ Low-level compatibility methods:
 | `completeImplementationTask(taskId, { completedBy })` | Mark complete. |
 
 ### Governed Implementation
+
+Current package version: `1.0.0-beta.13`.
+
 | Method | Description |
 |---|---|
 | `importImplementationPacket(body)` | Import an implementation packet. |
@@ -234,6 +529,26 @@ Low-level compatibility methods:
 | `getWorkflowImplementationRoadmap(workflowId)` | Workflow-linked roadmap. |
 | `getWorkflowResumeContext(workflowId)` | Resume context. |
 
+Governed roadmap item mutations must carry claim context. Include the active
+claim in the request body:
+
+```js
+await client.updateImplementationItemStatus(itemId, {
+  status: 'done',
+  status_reason: 'Evidence attached and gates passed.',
+  updated_by: 'operator:loga',
+  claimed_item_id: itemId,
+  agent_session_id: 'agent-session-id',
+  claim_workflow_run_id: 'workflow-run-id',
+});
+```
+
+The same claim envelope applies to `addImplementationItemEvidence()`,
+`addImplementationItemActivity()`, and `updateAcceptanceCheckStatus()`. If the
+claim is missing, AI Engine returns `409` with `error:
+missing_governed_claim`. If the claim exists but unresolved gates remain, AI
+Engine returns the required gate and next action.
+
 ### Skills
 | Method | Description |
 |---|---|
@@ -375,4 +690,4 @@ Low-level compatibility methods:
 
 The package talks to the AI Engine web service. All routes listed above are registered unconditionally in the Flask app and served by the deployed Azure Container App.
 
-Operator routes (`/api/operator/*`) use network-trust protection. The external v1 API (`/api/v1/*`) requires `X-Client-Id` and `X-API-Key` headers and is intentionally not wrapped by this client.
+Operator and governed routes generally expect bearer-token authorization. The package also wraps selected external `/api/v1/*` routes that support migration-oriented auth modes such as bearer or API-key compatibility, depending on deployment configuration.

package/examples/implementation-plan-packet.minimal.json

@@ -0,0 +1,76 @@
+{
+  "packetType": "implementation_plan_packet",
+  "packetVersion": "1.0",
+  "packetId": "impl-example-governed-slice-v1",
+  "title": "Example Governed Slice Implementation Packet",
+  "status": "draft",
+  "createdBy": {
+    "kind": "operator",
+    "name": "sdk-example"
+  },
+  "sourceModel": {
+    "producer": "ai-engine-client-readme",
+    "purpose": "minimal_import_example"
+  },
+  "system": {
+    "slug": "example-governed-slice",
+    "domain": "project-chartering"
+  },
+  "scope": {
+    "productArea": "example-governed-slice",
+    "workflowIntent": "Demonstrate the minimum durable implementation packet contract.",
+    "targetSurface": "governed-project-execution",
+    "inScope": [
+      "first delivery slice"
+    ],
+    "outOfScope": [
+      "full product rollout"
+    ]
+  },
+  "northStar": {
+    "summary": "Define a small but valid governed implementation packet."
+  },
+  "governance": {
+    "requiredGates": [
+      "intent",
+      "structure",
+      "promotion"
+    ],
+    "reviewRequired": true,
+    "evidenceRequiredForCompletion": true
+  },
+  "completionPolicy": {
+    "requiresEvidence": true,
+    "requiresReview": true
+  },
+  "phases": [
+    {
+      "phaseKey": "phase_1_foundation",
+      "title": "Foundation",
+      "items": [
+        {
+          "itemKey": "define-first-slice",
+          "type": "delivery_slice",
+          "priority": "high",
+          "title": "Define first governed slice",
+          "description": "Define the first durable delivery slice and bind its acceptance criteria.",
+          "status": "not_started",
+          "dependsOn": [],
+          "artifactsExpected": [
+            "delivery-slice-definition.md"
+          ],
+          "acceptanceChecks": [
+            {
+              "text": "The slice is explicitly bounded.",
+              "status": "not_run"
+            },
+            {
+              "text": "The slice can be attached to durable task surfaces.",
+              "status": "not_run"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.0.0-beta.8",
+  "version": "1.1.0",
   "description": "Thin npm client for the AI Engine operator and retrieval APIs",
   "type": "module",
   "main": "./src/index.js",
+  "scripts": {
+    "test": "node --test"
+  },
   "exports": {
     ".": "./src/index.js"
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "examples"
   ],
   "engines": {
     "node": ">=18"
@@ -25,4 +29,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/index.js

@@ -1,5 +1,10 @@
 const DEFAULT_TIMEOUT_MS = 30000;
 
+export const LOGA_CONTRACT = 'ai-engine-ui/v1';
+export const LOGA_INTERACTION_CONTRACT = 'loga-choreography/v1';
+export const LOGA_NAVIGATION_CONTRACT = 'loga-navigation/v1';
+export const LOGA_PROJECTION_WORKFLOW = 'loga-document-projection';
+
 function trimTrailingSlash(value) {
   return String(value || '').replace(/\/+$/, '');
 }
@@ -28,11 +33,74 @@ function parseContentDispositionFilename(headerValue) {
   return plainMatch ? plainMatch[1].trim() : null;
 }
 
+function readResponseHeader(headers, name) {
+  if (!headers || typeof headers.get !== 'function') return null;
+  return headers.get(name) || headers.get(name.toLowerCase()) || null;
+}
+
+function extractLogaProjectionMetadata(headers) {
+  const projectionWorkflow = readResponseHeader(headers, 'x-projection-workflow');
+  const projectionVersion = readResponseHeader(headers, 'x-projection-version');
+  const sourceVersion = readResponseHeader(headers, 'x-source-version');
+  const correlationId = readResponseHeader(headers, 'x-correlation-id');
+  const logaContract = readResponseHeader(headers, 'x-loga-contract');
+  const navigationContract = readResponseHeader(headers, 'x-navigation-contract');
+  const projectionType = readResponseHeader(headers, 'x-projection-type');
+  const sourceTruth = readResponseHeader(headers, 'x-source-truth');
+  const refreshPolicy = readResponseHeader(headers, 'x-refresh-policy');
+  const generatedAt = readResponseHeader(headers, 'x-generated-at');
+
+  return {
+    logaContract,
+    navigationContract,
+    interactionContract: LOGA_INTERACTION_CONTRACT,
+    projectionType,
+    projectionWorkflow,
+    projectionVersion,
+    sourceTruth,
+    sourceVersion,
+    correlationId,
+    refreshPolicy,
+    generatedAt,
+    provenance: {
+      sourceTruth,
+      sourceVersion,
+      projectionVersion,
+      projectionWorkflow,
+      correlationId,
+      generatedAt,
+    },
+  };
+}
+
+function isFormDataBody(value) {
+  return typeof FormData !== 'undefined' && value instanceof FormData;
+}
+
+function isBinaryBody(value) {
+  return (
+    value instanceof ArrayBuffer
+    || ArrayBuffer.isView(value)
+    || (typeof Blob !== 'undefined' && value instanceof Blob)
+    || value instanceof URLSearchParams
+    || typeof value === 'string'
+  );
+}
+
+function isJsonBody(value) {
+  if (value === undefined || value === null) return false;
+  if (isFormDataBody(value) || isBinaryBody(value)) return false;
+  return typeof value === 'object';
+}
+
 export class AIEngineClient {
-  constructor({ baseUrl, apiKey, actorId, fetchImpl, timeoutMs } = {}) {
+  constructor({ baseUrl, accessToken, tokenProvider, apiKey, clientId, actorId, fetchImpl, timeoutMs } = {}) {
     if (!baseUrl) throw new Error('baseUrl is required.');
     this.baseUrl = trimTrailingSlash(baseUrl);
+    this.accessToken = accessToken || null;
+    this.tokenProvider = tokenProvider || null;
     this.apiKey = apiKey || null;
+    this.clientId = clientId || null;
     this.actorId = actorId || 'sdk:npm-ai-engine-client';
     this.fetchImpl = fetchImpl || globalThis.fetch;
     this.timeoutMs = timeoutMs || DEFAULT_TIMEOUT_MS;
@@ -44,7 +112,10 @@ export class AIEngineClient {
   static fromEnv(options = {}) {
     return new AIEngineClient({
       baseUrl: options.baseUrl || process.env.AI_ENGINE_BASE_URL || process.env.AI_ENGINE_API_BASE_URL,
+      accessToken: options.accessToken || process.env.AI_ENGINE_ACCESS_TOKEN || null,
+      tokenProvider: options.tokenProvider || null,
       apiKey: options.apiKey || process.env.AI_ENGINE_API_KEY || null,
+      clientId: options.clientId || process.env.AI_ENGINE_CLIENT_ID || null,
       actorId: options.actorId || process.env.AI_ENGINE_ACTOR_ID || 'sdk:npm-ai-engine-client',
     });
   }
@@ -85,7 +156,7 @@ export class AIEngineClient {
   }
 
   async getLatestMemoryProjection() {
-    return this._request('/api/operator/latest-memory-projection');
+    return this._request('/api/v1/latest-memory-projection');
   }
 
   async currentProjectStatus({ projectId } = {}) {
@@ -209,6 +280,65 @@ export class AIEngineClient {
     return this._request('/api/dashboard');
   }
 
+  async startSessionGovernance(body) {
+    return this._request('/api/v1/session-governance/startup', { method: 'POST', body });
+  }
+
+  async persistAssistantTurn(body) {
+    return this._request('/api/v1/assistant-turns', { method: 'POST', body });
+  }
+
+  async getExternalProjectStatus(projectId) {
+    return this._request(`/api/v1/projects/${projectId}/status`);
+  }
+
+  async getExternalProjectRoadmapSummary(projectId) {
+    return this._request(`/api/v1/projects/${projectId}/implementation-roadmap/summary`);
+  }
+
+  async getExternalProjectRoadmapActiveItem(projectId) {
+    return this._request(`/api/v1/projects/${projectId}/implementation-roadmap/active-item`);
+  }
+
+  async listExternalProjectOpenTasks(projectId) {
+    return this._request(`/api/v1/projects/${projectId}/open-tasks`);
+  }
+
+  async getExternalProjectStatusBundle(projectId) {
+    return this._request(`/api/v1/projects/${projectId}/status-bundle`);
+  }
+
+  async createExternalAudioRender({ text, voice, model, speed, file } = {}) {
+    if (file) {
+      const form = new FormData();
+      form.append('file', file);
+      if (voice !== undefined) form.append('voice', String(voice));
+      if (model !== undefined) form.append('model', String(model));
+      if (speed !== undefined) form.append('speed', String(speed));
+      return this._request('/api/v1/audio-renders', { method: 'POST', body: form });
+    }
+    return this._request('/api/v1/audio-renders', {
+      method: 'POST',
+      body: { text, voice, model, speed },
+    });
+  }
+
+  async getExternalAudioRender(audioRenderRunId) {
+    return this._request(`/api/v1/audio-renders/${audioRenderRunId}`);
+  }
+
+  async downloadExternalAudioRender(audioRenderRunId) {
+    return this._requestBinary(`/api/v1/audio-renders/${audioRenderRunId}/download`);
+  }
+
+  async listExternalWorkflowRunArtifacts(workflowRunId) {
+    return this._request(`/api/v1/runs/${workflowRunId}/artifacts`);
+  }
+
+  async downloadExternalWorkflowRunArtifact(workflowRunId, artifactType) {
+    return this._requestBinary(`/api/v1/runs/${workflowRunId}/artifacts/${artifactType}/download`);
+  }
+
   // ─── Retrieval Wrapper ─────────────────────────────────────────────────────
 
   async getCommandCard({ commandKey, alias, intentText, requestedBy } = {}) {
@@ -505,6 +635,10 @@ export class AIEngineClient {
     return this._request(`/api/workflow-runs/${workflowRunId}/substrate`);
   }
 
+  async getWorkflowPlayback(workflowRunId) {
+    return this._request(`/api/operator/workflow-runs/${workflowRunId}/playback`);
+  }
+
   async resumeWorkflowRun(workflowRunId, body = {}) {
     return this._request(`/api/workflow-runs/${workflowRunId}/resume`, { method: 'POST', body });
   }
@@ -620,6 +754,32 @@ export class AIEngineClient {
     return this._request(`/api/operator/projects/${projectId}/bundle`);
   }
 
+  // LOGA projections are governed runtime documents, not static reports.
+
+  async getLogaOperatorHomeProjection() {
+    return this._requestLogaProjection('/api/operator/projections/home');
+  }
+
+  async getLogaProjectCatalogProjection() {
+    return this._requestLogaProjection('/api/operator/projections/project-catalog');
+  }
+
+  async getLogaProjectRoadmapProjection(projectId) {
+    return this._requestLogaProjection(`/api/operator/projections/projects/${projectId}/roadmap.md`);
+  }
+
+  async getLogaRoadmapItemProjection(projectId, itemKey) {
+    return this._requestLogaProjection(`/api/operator/projections/projects/${projectId}/roadmap/items/${itemKey}`);
+  }
+
+  async getLogaWorkflowRunProjection(workflowRunId) {
+    return this._requestLogaProjection(`/api/operator/projections/workflow-runs/${workflowRunId}`);
+  }
+
+  async getLogaEvidencePacketProjection(packetKey) {
+    return this._requestLogaProjection(`/api/operator/projections/evidence-packets/${packetKey}`);
+  }
+
   // ─── Roadmaps ──────────────────────────────────────────────────────────────
 
   async listProjectRoadmaps({ includeInactive } = {}) {
@@ -1217,23 +1377,177 @@ export class AIEngineClient {
     return this._request(`/api/benchmarks/reasoners/runs/${benchmarkRunId}`);
   }
 
+  // ─── Commit Governance ────────────────────────────────────────────────────
+
+  async evaluateCommitGovernance({
+    claimId,
+    contextSessionId,
+    agentId,
+    intentId,
+    changedFiles,
+    declaredScopeFiles,
+    diffSummary,
+    branch,
+    headSha,
+  } = {}) {
+    return this._request('/api/commit-governance/evaluate', {
+      method: 'POST',
+      body: {
+        claim_id: claimId,
+        context_session_id: contextSessionId,
+        agent_id: agentId,
+        intent_id: intentId,
+        changed_files: changedFiles,
+        declared_scope_files: declaredScopeFiles,
+        diff_summary: diffSummary,
+        branch,
+        head_sha: headSha,
+      },
+    });
+  }
+
+  async getCommitGovernanceEvaluation(evaluationId) {
+    return this._request(`/api/commit-governance/evaluations/${encodeURIComponent(evaluationId)}`);
+  }
+
+  async listCommitGovernanceEvaluationsByClaim(claimId, { limit } = {}) {
+    return this._request(`/api/commit-governance/claims/${encodeURIComponent(claimId)}/evaluations`, {
+      query: { limit },
+    });
+  }
+
+  // ─── Context Session Orientation ──────────────────────────────────────────
+
+  async openContextSession({ agentId, runtimeSessionId, intentId, executionPurpose, notes } = {}) {
+    return this._request('/api/context-session/open', {
+      method: 'POST',
+      body: {
+        agent_id: agentId,
+        runtime_session_id: runtimeSessionId,
+        intent_id: intentId,
+        execution_purpose: executionPurpose,
+        notes,
+      },
+    });
+  }
+
+  async getOrientationWindow(contextSessionId) {
+    return this._request(`/api/context-session/${encodeURIComponent(contextSessionId)}/window`);
+  }
+
+  async acknowledgeReminder(contextSessionId, { reminderId, agentSignature, understandingSummary } = {}) {
+    return this._request(`/api/context-session/${encodeURIComponent(contextSessionId)}/acknowledge`, {
+      method: 'POST',
+      body: {
+        reminder_id: reminderId,
+        agent_signature: agentSignature,
+        understanding_summary: understandingSummary,
+      },
+    });
+  }
+
+  async completeOrientation(contextSessionId) {
+    return this._request(`/api/context-session/${encodeURIComponent(contextSessionId)}/complete`, {
+      method: 'POST',
+    });
+  }
+
+  async lockContextSessionClaim(contextSessionId) {
+    return this._request(`/api/context-session/${encodeURIComponent(contextSessionId)}/lock-claim`, {
+      method: 'POST',
+    });
+  }
+
+  async getContextSessionGateStatus(contextSessionId) {
+    return this._request(`/api/context-session/${encodeURIComponent(contextSessionId)}/gate-status`);
+  }
+
+  async conductOrientation({
+    agentId,
+    runtimeSessionId,
+    intentId,
+    executionPurpose,
+    agentSignature,
+    understandingSummary,
+    lockClaim = true,
+  } = {}) {
+    const { context_session, reminders } = await this.openContextSession({
+      agentId,
+      runtimeSessionId,
+      intentId,
+      executionPurpose,
+    });
+    const sessionId = context_session.context_session_id;
+
+    const required = (reminders || []).filter(r => r.severity === 'required');
+    let acknowledgedCount = 0;
+    for (const reminder of required) {
+      await this.acknowledgeReminder(sessionId, {
+        reminderId: reminder.reminder_id,
+        agentSignature,
+        understandingSummary,
+      });
+      acknowledgedCount++;
+    }
+
+    const completion = await this.completeOrientation(sessionId);
+
+    let claimLockResult = null;
+    if (lockClaim) {
+      claimLockResult = await this.lockContextSessionClaim(sessionId);
+    }
+
+    return {
+      context_session_id: sessionId,
+      intent_id: intentId,
+      context_session: claimLockResult?.context_session || completion.context_session,
+      gate_result: claimLockResult?.gate_result || completion.gate_result,
+      acknowledged_count: acknowledgedCount,
+      claim_locked: lockClaim && !!claimLockResult,
+    };
+  }
+
   // ─── Core HTTP ─────────────────────────────────────────────────────────────
 
+  async _resolveAccessToken() {
+    if (typeof this.tokenProvider === 'function') {
+      const provided = await this.tokenProvider();
+      if (!provided) return null;
+      if (typeof provided === 'string') return provided;
+      if (typeof provided === 'object' && typeof provided.token === 'string') return provided.token;
+      if (typeof provided === 'object' && typeof provided.accessToken === 'string') return provided.accessToken;
+      throw new Error('tokenProvider must return a token string or an object with a token or accessToken field.');
+    }
+    return this.accessToken;
+  }
+
+  async _buildHeaders({ headers, body, accept }) {
+    const token = await this._resolveAccessToken();
+    const resolvedHeaders = {
+      accept: accept || 'application/json',
+      'x-actor-id': this.actorId,
+      ...(isJsonBody(body) ? { 'content-type': 'application/json' } : {}),
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+      ...(!token && this.clientId ? { 'x-client-id': this.clientId } : {}),
+      ...(!token && this.apiKey ? { 'x-api-key': this.apiKey } : {}),
+      ...headers,
+    };
+    for (const [key, value] of Object.entries(resolvedHeaders)) {
+      if (value === undefined) delete resolvedHeaders[key];
+    }
+    return resolvedHeaders;
+  }
+
   async _request(path, { method = 'GET', query, headers, body } = {}) {
     const url = appendQuery(`${this.baseUrl}${path}`, query);
     const controller = new AbortController();
     const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
     try {
+      const resolvedHeaders = await this._buildHeaders({ headers, body, accept: 'application/json' });
       const response = await this.fetchImpl(url, {
         method,
-        headers: {
-          accept: 'application/json',
-          'content-type': body ? 'application/json' : undefined,
-          'x-actor-id': this.actorId,
-          authorization: this.apiKey ? `Bearer ${this.apiKey}` : undefined,
-          ...headers,
-        },
-        body: body ? JSON.stringify(body) : undefined,
+        headers: resolvedHeaders,
+        body: isJsonBody(body) ? JSON.stringify(body) : body,
         signal: controller.signal,
       });
       const payload = await readJson(response);
@@ -1254,16 +1568,15 @@ export class AIEngineClient {
     const controller = new AbortController();
     const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
     try {
+      const resolvedHeaders = await this._buildHeaders({
+        headers,
+        body,
+        accept: 'text/markdown, text/plain;q=0.9, application/json;q=0.8',
+      });
       const response = await this.fetchImpl(url, {
         method,
-        headers: {
-          accept: 'text/markdown, text/plain;q=0.9, application/json;q=0.8',
-          'content-type': body ? 'application/json' : undefined,
-          'x-actor-id': this.actorId,
-          authorization: this.apiKey ? `Bearer ${this.apiKey}` : undefined,
-          ...headers,
-        },
-        body: body ? JSON.stringify(body) : undefined,
+        headers: resolvedHeaders,
+        body: isJsonBody(body) ? JSON.stringify(body) : body,
         signal: controller.signal,
       });
       const contentType = response.headers.get('content-type') || '';
@@ -1281,6 +1594,53 @@ export class AIEngineClient {
         text: await response.text(),
         contentType,
         fileName: parseContentDispositionFilename(contentDisposition),
+        headers: Object.fromEntries(response.headers.entries()),
+      };
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  }
+
+  async _requestLogaProjection(path, options = {}) {
+    const result = await this._requestText(path, options);
+    return {
+      ...result,
+      ...extractLogaProjectionMetadata(new Headers(result.headers || {})),
+    };
+  }
+
+  async _requestBinary(path, { method = 'GET', query, headers, body } = {}) {
+    const url = appendQuery(`${this.baseUrl}${path}`, query);
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const resolvedHeaders = await this._buildHeaders({
+        headers,
+        body,
+        accept: 'audio/mpeg, application/octet-stream;q=0.9, application/json;q=0.8',
+      });
+      const response = await this.fetchImpl(url, {
+        method,
+        headers: resolvedHeaders,
+        body: isJsonBody(body) ? JSON.stringify(body) : body,
+        signal: controller.signal,
+      });
+      const contentType = response.headers.get('content-type') || '';
+      const contentDisposition = response.headers.get('content-disposition') || '';
+      if (!response.ok) {
+        const payload = contentType.includes('application/json')
+          ? await response.json()
+          : { message: await response.text() };
+        const error = new Error(payload?.message || payload?.error || `Request failed with status ${response.status}.`);
+        error.status = response.status;
+        error.payload = payload;
+        throw error;
+      }
+      const arrayBuffer = await response.arrayBuffer();
+      return {
+        arrayBuffer,
+        contentType,
+        fileName: parseContentDispositionFilename(contentDisposition),
       };
     } finally {
       clearTimeout(timeoutHandle);