@bpmsoftwaresolutions/ai-engine-client 1.1.101 → 1.1.103

package/README.md

@@ -1,6 +1,6 @@
 # @bpmsoftwaresolutions/ai-engine-client
 
-Full-surface npm client for the AI Engine. Covers every operator, workflow, project, retrieval, performance, and governance endpoint exposed by the deployed service.
+Full-surface npm client for the AI Engine. The SDK is now workflow-oriented and composed from focused domain modules, shared transport, and compatibility aliases.
 
 No repo clone required. Install the package, point it at the Azure service, and call any method.
 
@@ -79,15 +79,130 @@ const generatedUsability = await client.getGeneratedExecutionUsability();
 const logaUsability = await client.getLogaGeneratedExecutionUsabilityProjection();
 ```
 
+## Architecture Overview
+
+The composed SDK follows this flow:
+
+`AIEngineClient` → composed namespaces → focused domain modules → shared transport → compatibility aliases → governed request-contract testing
+
+| File | Role |
+|---|---|
+| `index.js` | Public barrel only. Re-exports the client, version, and constants. |
+| `client.js` | Constructor, composition root, transport bridge, namespace attachment, and thin compatibility wiring. |
+| `domains/*` | Canonical implementation ownership for endpoint bodies and workflow helpers. |
+| `compat/*` | Compatibility alias and facade preservation. |
+| `transport/*` | Shared request execution, auth header handling, and response shaping. |
+| `utils/*` | Shared normalization, parsing, and helper utilities used across domains. |
+| `test/request-contract-fixtures.*` | Request-contract parity fixtures that guard the public surface. |
+
+### Domain Topology
+
+| Namespace | Responsibility |
+|---|---|
+| `projects` | Project lifecycle, bundle surfaces, closure readiness, and completion views |
+| `projectChartering` | Project charter creation and roadmap bootstrap helpers |
+| `roadmaps` | Roadmap state, active item lookup, and task-surface visibility |
+| `implementationPackets` | Implementation packet operations and workflow binding |
+| `implementationItems` | Item status, activity, and verified mutation surfaces |
+| `implementationChecks` | Acceptance-check retrieval and status updates |
+| `implementationArtifacts` | Artifact manifest, decision packets, and verification |
+| `implementationEvidence` | Evidence attachment and proof collection |
+| `implementationGates` | Gate decisions for implementation packet review |
+| `agentComms` | Governed multi-agent communication and transfer primitives |
+| `collaboration` | Collaboration proposals, blockers, ownership, and heartbeats |
+| `executionTelemetry` | Execution telemetry, process runs, and monitoring views |
+| `projections` | LOGA/runtime markdown projections and navigation surfaces |
+| `retrieval` | Symbol and code retrieval helpers |
+| `workflows` | Workflow definitions and workflow-run surfaces |
+| `workflowComposition` | Legacy modernization composition helpers and compatibility surface |
+| `database` | Query, backups, and schema inspection helpers |
+| `skills` | Skill contracts and skill governance |
+| `toolRegistry` | Tool registry lookup and tool-governance surfaces |
+| `capabilities` | Capability discovery and smoke-test surfaces |
+| `performance` | Session performance and benchmark summaries |
+| `designIntelligence` | Design decision, critique, promotion, and recommendation surfaces |
+| `notesLab` | Note submission and review workflow |
+| `searchContacts` | Organization and contact lookup |
+| `benchmarks` | Benchmark run history and trend lookup |
+
+## Workflow-Oriented SDK Model
+
+The SDK is workflow-oriented, not a pile of 370+ isolated methods. Domain namespaces compose into executable workflows, and those workflows map to governed AI Engine operations.
+
+Common workflow families include:
+
+- Agent Session Startup
+- Project Chartering
+- Governed Work / Claims
+- Roadmap Item Execution
+- Commit Governance
+- Agent Communication
+- Work Transfer & Handoff
+- Workflow Governance
+- Code Analysis & Refactoring
+- Retrieval-Augmented Prompt Assembly
+- Warehouse Modernization Pipeline
+
+For full workflow chains, see `docs/sdk-workflow-taxonomy.md`.
+
+Namespace paths are canonical. Top-level methods remain supported compatibility aliases.
+
+### Workflow Example
+
+```js
+const client = AIEngineClient.fromEnv();
+
+const startup = await client.projectResume.resumeProjectWork({
+  projectIdentifier: 'my-project',
+  actorMode: 'agent',
+  executionIntent: 'continue roadmap delivery',
+});
+
+const activeItem = await client.roadmaps.getProjectRoadmapActiveItem(
+  startup.project.project_id,
+);
+
+const checks = await client.implementationChecks.getImplementationItemAcceptanceChecks(
+  activeItem.implementation_item_id,
+);
+```
+
+## Workflow and Governance Posture
+
+The SDK is not just CRUD transport. It wraps workflow orchestration, governed execution, claims, session governance, multi-agent coordination, LOGA projections, and evidence-backed workflow delivery.
+
+Execution substrate primitives such as `startWork()`, `completeTurn()`, and `runCharter()` exist to move work through governed stages instead of leaving the caller to assemble those chains manually.
+
+## Repo-less Retrieval Posture
+
+The retrieval and code-intelligence namespaces are designed for bounded retrieval, symbol lookup, intent discovery, repo-less operation, and governed code-context assembly.
+
+That means the SDK can be used against deployed service state without requiring a local repo clone, while still preserving provenance and the workflow boundaries that make the result safe to execute.
+
+## Multi-Agent Coordination
+
+Transfer packets, communication channels, receipts, message watches, presence, handoffs, and collaboration proposals are exposed as governed coordination primitives.
+
+The SDK intentionally models these flows as structured workflows rather than free-form chat so that every cross-agent exchange remains auditable and tied to a bounded work surface.
+
 ## Namespaces
 
-The client keeps the top-level compatibility methods, but the extracted domain namespaces are the preferred way to navigate the SDK:
+The extracted domain namespaces are the preferred way to navigate the SDK. Top-level compatibility methods remain available for backward compatibility.
 
 - `client.portfolio` for portfolio status and closure-readiness views
 - `client.workflowComposition` for modernization and workflow-composition helpers
 - `client.warehouse` as a legacy compatibility alias for the workflow-composition helpers
 - `client.projects`, `client.roadmaps`, `client.projectChartering`, and other domain namespaces for the thinner wrapper surfaces
 
+Preferred usage is namespace-first:
+
+```js
+await client.projects.getProjectBundle(projectId);
+await client.roadmaps.getProjectRoadmap(projectId);
+await client.executionTelemetry.getExecutionTelemetryCurrent();
+await client.agentComms.openTransferChannel({ projectIdentifier: projectId });
+```
+
 The legacy top-level methods still work, so existing callers can move gradually:
 
 ```js
@@ -284,6 +399,8 @@ Header behavior is:
 - 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.
 
+`tokenProvider` is the preferred boundary for short-lived bearer credentials, with API-key compatibility mode preserved for deployments that still rely on shared keys. The service is expected to migrate toward bearer-oriented OIDC/OAuth flows, but the client preserves the legacy auth shape so existing deployments keep working.
+
 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
@@ -353,6 +470,12 @@ await fs.promises.writeFile('render.mp3', Buffer.from(audio.arrayBuffer));
 
 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 flow is:
+
+`SQL truth` → `projection generation` → `structured markdown` → `LOGA runtime rendering`
+
+Markdown is projection, not authority. Provenance metadata is preserved so renderers can validate origin, version, and refresh behavior before displaying the result. These projections are versioned runtime documents, not free-form documentation files.
+
 The client exposes the transport metadata from response headers so LOGA can validate the contract before rendering:
 
 - `logaContract`: currently `ai-engine-ui/v1`

package/package.json

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

package/src/client.js

@@ -146,6 +146,7 @@ export class AIEngineClient {
     this.reports = createReportsDomain(this);
     this.projections = createProjectionsDomain(this);
     this.workflowComposition = createWorkflowCompositionDomain(this);
+    this.workflowComposition.searchCodeByIntent = (request) => this.searchCodeByIntent(request);
     this.warehouse = createWarehouseDomain(this);
     this.actions = createActionsDomain(this);
     this.transferBundles = createTransferBundlesDomain(this);
@@ -162,6 +163,7 @@ export class AIEngineClient {
     this.collaborationDomain = createCollaborationDomain(this);
     this.agentComms = createAgentCommunicationsFacade(this);
     this.collaboration = createCollaborationFacade(this);
+    this.collaboration.postCollaborationProposal = (request) => this.postCollaborationProposal(request);
   }
 
   static fromEnv(options = {}) {

package/src/compat/aliases.js

@@ -5,6 +5,7 @@ export const COMPATIBILITY_ALIAS_GROUPS = [
       'ping',
       'query',
       'getPortfolioClosureReadiness',
+      'searchCodeByIntent',
       'registerModernizationAsset',
       'classifyModernizationAsset',
       'discoverSalvageCandidates',
@@ -187,7 +188,7 @@ export function installClientCompatibilityDelegates(ClientClass) {
   defineCompatibilityMethods(proto, 'presence', ['getPresenceBoard', 'getChannelPresence', 'markParticipantOnline', 'markParticipantOffline', 'whoIsOnline', 'findOnlineParticipant', 'sendToParticipant', 'sendToRole', 'postPresenceHeartbeat']);
   defineCompatibilityMethods(proto, 'collaborationDomain', ['reviewCollaborationProposal', 'reviseCollaborationProposal', 'postCollaborationProposal', 'acceptCollaborationProposal', 'assignCollaborationOwnership', 'raiseCollaborationBlocker', 'resolveCollaborationBlocker', 'postCollaborationHeartbeat', 'beginCollaborationImplementation', 'requestCollaborationClosure']);
   defineCompatibilityMethods(proto, 'transferBundles', ['transferWorkPacket', 'getTransferBundle', 'listTransferBundles', 'createTransferReceipt', 'listTransferReceipts', 'createCommunicationBundle', 'getCommunicationBundle', 'listCommunicationBundles', 'addCommunicationBundleItem', 'uploadCommunicationBundle', 'attachCommunicationBundleToMessage', 'recordCommunicationBundleReceipt', 'recordCommunicationBundleCleanupEvent', 'claimCommunicationBundle', 'recordCommunicationTransferReceipt']);
-  defineCompatibilityMethods(proto, 'workflowComposition', ['registerModernizationAsset', 'classifyModernizationAsset', 'discoverSalvageCandidates', 'createModernizationWorkPacket', 'requestModernizationWrapperExecution', 'getModernizationWrapperEvidence', 'decideModernizationGate']);
+  defineCompatibilityMethods(proto, 'workflowComposition', ['registerModernizationAsset', 'classifyModernizationAsset', 'discoverSalvageCandidates', 'createModernizationWorkPacket', 'requestModernizationWrapperExecution', 'getModernizationWrapperEvidence', 'decideModernizationGate', 'searchCodeByIntent']);
   defineCompatibilityMethods(proto, 'currentProject', ['currentProjectStatus']);
   defineCompatibilityMethods(proto, 'projections', ['renderProjection', 'getLogaOperatorHomeProjection', 'getLogaProjectCatalogProjection', 'getLogaProjectPortfolioProjection', 'getLogaProjectRoadmapProjection', 'getLogaRoadmapItemProjection', 'getLogaWorkflowRunProjection', 'getLogaEvidencePacketProjection', 'getLogaTransferHomeProjection', 'getLogaTransferInboxProjection', 'getLogaTransferPacketProjection', 'getLogaTransferNegotiationEventsProjection', 'getLogaTransferFrictionLaneProjection', 'getLogaTransferReceiptsProjection', 'getLogaTransferClosureReviewProjection', 'getTransferChannelProjection']);
   defineCompatibilityAliases(proto, 'projections', { getLogaTransferChannelThreadProjection: 'getTransferChannelProjection' });

package/src/index.js

@@ -1,5 +1,5 @@
 export { AIEngineClient, createAIEngineClient } from './client.js';
-export const AI_ENGINE_CLIENT_VERSION = '1.1.101';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.103';
 export { GOVERNED_MUTATION_REQUIRED_CAPABILITIES, AI_ENGINE_CLIENT_CAPABILITIES, TASK_BOUND_SUBSTRATE_EXECUTION_POLICY } from './constants/governance.js';
 export { LOGA_CONTRACT, LOGA_INTERACTION_CONTRACT, LOGA_NAVIGATION_CONTRACT, LOGA_PROJECTION_WORKFLOW } from './constants/loga.js';
 export {