@bpmsoftwaresolutions/ai-engine-client 1.0.0-beta.11 → 1.0.0-beta.13

package/README.md

@@ -94,7 +94,8 @@ If your deployment enforces bearer auth on operator routes, API-key-only constru
 
 Some methods do not return plain JSON:
 
-- Markdown download helpers return `{ text, contentType, fileName }`.
+- 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:
@@ -106,10 +107,60 @@ 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
@@ -321,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 |
 |---|---|
@@ -448,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. |
@@ -463,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 |
 |---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.0.0-beta.11",
+  "version": "1.0.0-beta.13",
   "description": "Thin npm client for the AI Engine operator and retrieval APIs",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -1,5 +1,9 @@
 const DEFAULT_TIMEOUT_MS = 30000;
 
+export const LOGA_CONTRACT = 'ai-engine-ui/v1';
+export const LOGA_INTERACTION_CONTRACT = 'loga-choreography/v1';
+export const LOGA_PROJECTION_WORKFLOW = 'loga-document-projection';
+
 function trimTrailingSlash(value) {
   return String(value || '').replace(/\/+$/, '');
 }
@@ -28,6 +32,44 @@ 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 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,
+    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;
 }
@@ -709,6 +751,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 } = {}) {
@@ -1393,12 +1461,21 @@ 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();