@romiluz/clawmongo 0.1.0-rc.0

package/dist/modules/ingestion/service.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { appendIngestionHookToOutbox } from "../eventing/service.js";
+const nonEmptyString = z.string().trim().min(1);
+const ingestionHookRequestSchema = z.object({
+    tenant_id: nonEmptyString,
+    aggregate_id: nonEmptyString,
+    hook_name: nonEmptyString,
+    hook_key: nonEmptyString,
+    payload: z.unknown(),
+    trace_id: nonEmptyString
+});
+function mapEnvelope(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return input;
+    }
+    const value = input;
+    return {
+        ...value,
+        tenant_id: value.tenant_id ?? value.tenantId,
+        aggregate_id: value.aggregate_id ?? value.aggregateId,
+        hook_name: value.hook_name ?? value.hookName,
+        hook_key: value.hook_key ?? value.hookKey,
+        trace_id: value.trace_id ?? value.traceId
+    };
+}
+export function executeIngestionHookAppend(input) {
+    const parsed = ingestionHookRequestSchema.safeParse(mapEnvelope(input));
+    if (!parsed.success) {
+        return {
+            ok: false,
+            error: {
+                code: "VALIDATION_ERROR",
+                message: "Invalid ingestion hook append request.",
+                details: {
+                    boundary: "ingestion->eventing.v1",
+                    issues: parsed.error.issues.map((issue) => ({
+                        path: issue.path.join("."),
+                        code: issue.code,
+                        message: issue.message
+                    }))
+                }
+            }
+        };
+    }
+    return {
+        ok: true,
+        outbox_result: appendIngestionHookToOutbox({
+            tenant_id: parsed.data.tenant_id,
+            aggregate_id: parsed.data.aggregate_id,
+            hook_name: parsed.data.hook_name,
+            hook_key: parsed.data.hook_key,
+            payload: parsed.data.payload ?? null,
+            trace_id: parsed.data.trace_id
+        })
+    };
+}

package/dist/modules/mongo-store/index.js

@@ -0,0 +1,21 @@
+import { bootstrapMongoStore } from "../../store/mongo/bootstrap.js";
+export const moduleDefinition = {
+    name: "mongo-store",
+    contractVersion: "v1",
+    boundaries: ["mongo-store->collections.v1"],
+    async start(ctx) {
+        const result = await bootstrapMongoStore({
+            deploymentProfile: ctx.deploymentProfile,
+            ...ctx.mongo
+        });
+        return {
+            status: result.status,
+            details: {
+                code: result.code,
+                retryable: result.retryable,
+                message: result.message,
+                ...result.details
+            }
+        };
+    }
+};

package/dist/modules/observability/index.js

@@ -0,0 +1,6 @@
+import { createStubModule } from "../stub.js";
+export const moduleDefinition = createStubModule({
+    name: "observability",
+    contractVersion: "v1",
+    boundaries: ["all-modules->observability.v1"]
+});

package/dist/modules/orchestrator/index.js

@@ -0,0 +1,49 @@
+import { createDefaultOrchestratorDependencies, executeOrchestratorRequest } from "./service.js";
+const orchestratorDependencies = createDefaultOrchestratorDependencies();
+export const moduleDefinition = {
+    name: "orchestrator",
+    contractVersion: "v1",
+    boundaries: ["orchestrator->retrieval.v1", "orchestrator->provider.v1", "orchestrator->tool-runtime.v1"],
+    async start(ctx) {
+        try {
+            const sampleResponse = await executeOrchestratorRequest({
+                request_id: `orchestrator-boot-${ctx.requestId}`,
+                tenant_id: "tenant-demo",
+                workspace_id: "workspace-alpha",
+                actor: "system:bootstrap",
+                session_key: "agent:agent-alpha:main",
+                input_payload: {
+                    text: "boot health check",
+                    tool_call: {
+                        tool_name: "health_probe",
+                        params: {
+                            deployment_profile: ctx.deploymentProfile
+                        }
+                    }
+                },
+                mode: "sync"
+            }, orchestratorDependencies);
+            return {
+                status: sampleResponse.status === "ok" ? "ready" : "degraded",
+                details: {
+                    deploymentProfile: ctx.deploymentProfile,
+                    sampleStatus: sampleResponse.status,
+                    errorCount: sampleResponse.errors.length,
+                    timings: sampleResponse.timings,
+                    note: "orchestrator runtime baseline initialized"
+                }
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                status: "degraded",
+                details: {
+                    deploymentProfile: ctx.deploymentProfile,
+                    error: message,
+                    note: "orchestrator runtime baseline failed"
+                }
+            };
+        }
+    }
+};

package/dist/modules/orchestrator/service.js

@@ -0,0 +1,220 @@
+import { performance } from "node:perf_hooks";
+import { validateGatewayToOrchestratorRequest, validateOrchestratorToProviderRequest, validateOrchestratorToToolRuntimeRequest } from "../../contracts/validators.js";
+import { executeProviderAdapter, ProviderAdapterExecutionError } from "../provider-adapter/service.js";
+import { executeToolRuntime } from "../tool-runtime/service.js";
+function roundedDuration(startedAt) {
+    return Number((performance.now() - startedAt).toFixed(3));
+}
+function dependencyError(stage, error) {
+    if (error instanceof ProviderAdapterExecutionError) {
+        return {
+            code: error.code,
+            message: `${stage} dependency failed: ${error.message}`,
+            retryable: error.retryable,
+            details: {
+                stage,
+                ...error.details
+            }
+        };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        code: "DEPENDENCY_UNAVAILABLE",
+        message: `${stage} dependency failed: ${message}`,
+        retryable: true,
+        details: {
+            stage
+        }
+    };
+}
+function toolRuntimeFailureError(response) {
+    const resultPayload = typeof response.result === "object" && response.result !== null
+        ? response.result
+        : {};
+    const code = typeof resultPayload.error_code === "string"
+        ? resultPayload.error_code
+        : "NON_RETRYABLE_FAILURE";
+    const retryable = resultPayload.retryable === true;
+    return {
+        code,
+        message: `tool-runtime returned status=${response.status}`,
+        retryable,
+        details: {
+            tool_call_id: response.tool_call_id,
+            ...(typeof resultPayload.message === "string" ? { reason: resultPayload.message } : {})
+        }
+    };
+}
+function coerceRequestId(input) {
+    if (typeof input === "object" && input !== null) {
+        const value = input.request_id;
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value;
+        }
+    }
+    return "invalid-request";
+}
+function buildRetrievalRequest(request) {
+    const payload = typeof request.input_payload === "object" && request.input_payload !== null
+        ? request.input_payload
+        : {};
+    const querySource = typeof payload.query === "string"
+        ? payload.query
+        : typeof payload.text === "string"
+            ? payload.text
+            : "orchestrator-default-query";
+    return {
+        query: querySource,
+        scope_filters: {
+            tenant_id: request.tenant_id,
+            workspace_id: request.workspace_id,
+            session_key: request.session_key
+        },
+        top_k: 5,
+        retrieval_profile: "hybrid"
+    };
+}
+function buildProviderRequest(request) {
+    const payload = typeof request.input_payload === "object" && request.input_payload !== null
+        ? request.input_payload
+        : {};
+    const messages = Array.isArray(payload.messages)
+        ? payload.messages
+        : [
+            {
+                role: "user",
+                content: typeof payload.text === "string" ? payload.text : request.actor
+            }
+        ];
+    return {
+        provider: typeof payload.provider === "string" ? payload.provider : "openai",
+        model: typeof payload.model === "string" ? payload.model : "gpt-5-mini",
+        messages,
+        tool_context: {
+            tenant_id: request.tenant_id,
+            workspace_id: request.workspace_id,
+            session_key: request.session_key
+        },
+        generation_config: typeof payload.generation_config === "object" && payload.generation_config !== null
+            ? payload.generation_config
+            : {}
+    };
+}
+function buildToolRuntimeRequest(request) {
+    const payload = typeof request.input_payload === "object" && request.input_payload !== null
+        ? request.input_payload
+        : {};
+    const tool = payload.tool_call;
+    if (typeof tool !== "object" || tool === null) {
+        return null;
+    }
+    const toolObject = tool;
+    return {
+        tool_name: toolObject.tool_name ?? toolObject.toolName,
+        tool_call_id: toolObject.tool_call_id ?? toolObject.toolCallId ?? `${request.request_id}-tool`,
+        params: typeof toolObject.params === "object" && toolObject.params !== null ? toolObject.params : {},
+        policy_context: typeof toolObject.policy_context === "object" && toolObject.policy_context !== null
+            ? toolObject.policy_context
+            : {
+                tenant_id: request.tenant_id,
+                workspace_id: request.workspace_id
+            }
+    };
+}
+function toResponse(requestId, result, errors, timings) {
+    return {
+        request_id: requestId,
+        status: errors.length === 0 ? "ok" : "error",
+        result,
+        errors,
+        timings
+    };
+}
+export async function executeOrchestratorRequest(input, deps) {
+    const totalStartedAt = performance.now();
+    const timings = {};
+    const errors = [];
+    const requestId = coerceRequestId(input);
+    const validationStartedAt = performance.now();
+    const gatewayValidation = validateGatewayToOrchestratorRequest(input);
+    timings.validation_ms = roundedDuration(validationStartedAt);
+    if (!gatewayValidation.ok) {
+        errors.push(gatewayValidation.error);
+        timings.total_ms = roundedDuration(totalStartedAt);
+        return toResponse(requestId, null, errors, timings);
+    }
+    const gatewayRequest = gatewayValidation.value;
+    let retrievalResponse = null;
+    const retrievalStartedAt = performance.now();
+    try {
+        retrievalResponse = await deps.retrieval(buildRetrievalRequest(gatewayRequest));
+    }
+    catch (error) {
+        errors.push(dependencyError("retrieval", error));
+    }
+    timings.retrieval_ms = roundedDuration(retrievalStartedAt);
+    const providerValidationStartedAt = performance.now();
+    const providerValidation = validateOrchestratorToProviderRequest(buildProviderRequest(gatewayRequest));
+    timings.provider_validation_ms = roundedDuration(providerValidationStartedAt);
+    if (!providerValidation.ok) {
+        errors.push(providerValidation.error);
+        timings.total_ms = roundedDuration(totalStartedAt);
+        return toResponse(gatewayRequest.request_id, { retrieval: retrievalResponse }, errors, timings);
+    }
+    let providerResponse = null;
+    const providerStartedAt = performance.now();
+    try {
+        providerResponse = await deps.provider(providerValidation.value);
+    }
+    catch (error) {
+        errors.push(dependencyError("provider", error));
+    }
+    timings.provider_ms = roundedDuration(providerStartedAt);
+    let toolRuntimeResponse = null;
+    const toolRuntimeStartedAt = performance.now();
+    const toolRuntimeCandidate = buildToolRuntimeRequest(gatewayRequest);
+    if (toolRuntimeCandidate !== null) {
+        const toolValidation = validateOrchestratorToToolRuntimeRequest(toolRuntimeCandidate);
+        if (!toolValidation.ok) {
+            errors.push(toolValidation.error);
+        }
+        else {
+            try {
+                toolRuntimeResponse = await deps.toolRuntime(toolValidation.value);
+                if (toolRuntimeResponse.status === "error") {
+                    errors.push(toolRuntimeFailureError(toolRuntimeResponse));
+                }
+            }
+            catch (error) {
+                errors.push(dependencyError("tool-runtime", error));
+            }
+        }
+    }
+    timings.tool_runtime_ms = roundedDuration(toolRuntimeStartedAt);
+    timings.total_ms = roundedDuration(totalStartedAt);
+    return toResponse(gatewayRequest.request_id, {
+        retrieval: retrievalResponse,
+        provider: providerResponse,
+        ...(toolRuntimeResponse ? { tool_runtime: toolRuntimeResponse } : {})
+    }, errors, timings);
+}
+export function createDefaultOrchestratorDependencies() {
+    return {
+        retrieval: async (request) => ({
+            results: [
+                {
+                    id: "orchestrator-default-result",
+                    score: 1,
+                    query: request.query
+                }
+            ],
+            pipeline_mode: "hybrid",
+            degraded: false,
+            debug: {
+                source: "orchestrator-default-retrieval"
+            }
+        }),
+        provider: async (request) => executeProviderAdapter(request),
+        toolRuntime: async (request) => executeToolRuntime(request)
+    };
+}

package/dist/modules/policy-engine/index.js

@@ -0,0 +1,34 @@
+import { evaluateToolPolicy } from "./service.js";
+export const moduleDefinition = {
+    name: "policy-engine",
+    contractVersion: "v1",
+    boundaries: ["tool-runtime->policy-engine.v1"],
+    async start(ctx) {
+        const allowDecision = evaluateToolPolicy({
+            tool_name: "fetch_profile",
+            tool_call_id: "policy-allow-001",
+            params: {},
+            policy_context: {
+                tenant_id: "tenant-demo"
+            }
+        });
+        const denyDecision = evaluateToolPolicy({
+            tool_name: "internal.rebuild_index",
+            tool_call_id: "policy-deny-001",
+            params: {},
+            policy_context: {
+                tenant_id: "tenant-demo",
+                allow_internal_tools: false
+            }
+        });
+        return {
+            status: allowDecision.allow && !denyDecision.allow ? "ready" : "degraded",
+            details: {
+                deploymentProfile: ctx.deploymentProfile,
+                allowDecision,
+                denyDecision,
+                note: "policy engine runtime baseline initialized"
+            }
+        };
+    }
+};

package/dist/modules/policy-engine/service.js

@@ -0,0 +1,42 @@
+function readBoolean(value) {
+    return value === true;
+}
+export function evaluateToolPolicy(request) {
+    const context = request.policy_context;
+    const params = request.params;
+    if (readBoolean(context.blocked)) {
+        return {
+            allow: false,
+            reason: "context_blocked",
+            policySignals: {
+                blocked: true
+            }
+        };
+    }
+    if (readBoolean(params.requires_admin) && !readBoolean(context.is_admin)) {
+        return {
+            allow: false,
+            reason: "admin_required",
+            policySignals: {
+                requires_admin: true,
+                is_admin: false
+            }
+        };
+    }
+    if (request.tool_name.startsWith("internal.") && !readBoolean(context.allow_internal_tools)) {
+        return {
+            allow: false,
+            reason: "internal_tool_denied",
+            policySignals: {
+                allow_internal_tools: false
+            }
+        };
+    }
+    return {
+        allow: true,
+        reason: "policy_pass",
+        policySignals: {
+            blocked: false
+        }
+    };
+}

package/dist/modules/provider-adapter/index.js

@@ -0,0 +1,37 @@
+import { executeProviderAdapterRequest } from "./service.js";
+export const moduleDefinition = {
+    name: "provider-adapter",
+    contractVersion: "v1",
+    boundaries: ["orchestrator->provider.v1"],
+    async start(ctx) {
+        const sample = executeProviderAdapterRequest({
+            provider: "openai",
+            model: "gpt-5-mini",
+            messages: [{ role: "user", content: "provider health check" }],
+            tool_context: {
+                tenant_id: "tenant-demo",
+                workspace_id: "workspace-alpha",
+                deployment_profile: ctx.deploymentProfile
+            },
+            generation_config: {}
+        });
+        if (!sample.ok) {
+            return {
+                status: "degraded",
+                details: {
+                    deploymentProfile: ctx.deploymentProfile,
+                    error: sample.error
+                }
+            };
+        }
+        return {
+            status: "ready",
+            details: {
+                deploymentProfile: ctx.deploymentProfile,
+                providerMetadata: sample.response.provider_metadata,
+                safetySignals: sample.response.safety_signals,
+                note: "provider adapter runtime baseline initialized"
+            }
+        };
+    }
+};

package/dist/modules/provider-adapter/service.js

@@ -0,0 +1,98 @@
+import { validateOrchestratorToProviderRequest } from "../../contracts/validators.js";
+const SUPPORTED_PROVIDERS = new Set(["openai", "anthropic", "google", "voyage"]);
+export class ProviderAdapterExecutionError extends Error {
+    code;
+    retryable;
+    details;
+    constructor(error) {
+        super(error.message);
+        this.name = "ProviderAdapterExecutionError";
+        this.code = error.code;
+        this.retryable = error.retryable;
+        this.details = error.details;
+    }
+}
+function toFailure(code, message, retryable, details) {
+    return {
+        code,
+        message,
+        retryable,
+        details
+    };
+}
+function readForceErrorMode(request) {
+    const mode = request.generation_config.force_provider_error;
+    return typeof mode === "string" && mode.trim().length > 0 ? mode : undefined;
+}
+function buildSuccessResponse(request) {
+    return {
+        output: {
+            role: "assistant",
+            content: `provider:${request.provider};model:${request.model};messages:${request.messages.length}`
+        },
+        usage: {
+            input_tokens: 128,
+            output_tokens: 64
+        },
+        provider_metadata: {
+            provider: request.provider,
+            model: request.model,
+            execution_mode: "deterministic-mock",
+            retry_classification: "none"
+        },
+        safety_signals: {
+            blocked: false,
+            moderation: "pass"
+        }
+    };
+}
+export function executeProviderAdapterRequest(input) {
+    const validation = validateOrchestratorToProviderRequest(input);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            error: validation.error
+        };
+    }
+    const request = validation.value;
+    const providerKey = request.provider.toLowerCase();
+    if (!SUPPORTED_PROVIDERS.has(providerKey)) {
+        return {
+            ok: false,
+            error: toFailure("NON_RETRYABLE_FAILURE", `Unsupported provider '${request.provider}'.`, false, {
+                provider: request.provider,
+                supported_providers: Array.from(SUPPORTED_PROVIDERS.values())
+            })
+        };
+    }
+    const forceErrorMode = readForceErrorMode(request);
+    if (forceErrorMode === "retryable") {
+        return {
+            ok: false,
+            error: toFailure("RETRYABLE_FAILURE", "Provider adapter forced retryable failure mode.", true, {
+                provider: request.provider,
+                model: request.model
+            })
+        };
+    }
+    if (forceErrorMode === "non_retryable") {
+        return {
+            ok: false,
+            error: toFailure("NON_RETRYABLE_FAILURE", "Provider adapter forced non-retryable failure mode.", false, {
+                provider: request.provider,
+                model: request.model
+            })
+        };
+    }
+    return {
+        ok: true,
+        response: buildSuccessResponse(request)
+    };
+}
+export async function executeProviderAdapter(request) {
+    const result = executeProviderAdapterRequest(request);
+    if (result.ok) {
+        return result.response;
+    }
+    throw new ProviderAdapterExecutionError(result.error);
+}

package/dist/modules/retrieval/index.js

@@ -0,0 +1,64 @@
+import { RetrievalEngine } from "../../retrieval/engine.js";
+import { AdaptiveFusionRetriever } from "../../retrieval/providers/fusion.js";
+import { MongoLexicalRetriever, StubLexicalRetriever } from "../../retrieval/providers/lexical.js";
+import { MongoVectorRetriever, StubVectorRetriever } from "../../retrieval/providers/vector.js";
+function hasNativeFusion(profile) {
+    return profile !== "atlas-m0";
+}
+export const moduleDefinition = {
+    name: "retrieval-service",
+    contractVersion: "v1",
+    boundaries: ["orchestrator->retrieval.v1", "retrieval->mongo-store.v1"],
+    async start(ctx) {
+        const lexicalProvider = ctx.mongo.uri
+            ? new MongoLexicalRetriever({
+                deploymentProfile: ctx.deploymentProfile,
+                uri: ctx.mongo.uri,
+                dbName: ctx.mongo.dbName,
+                connectTimeoutMs: ctx.mongo.connectTimeoutMs
+            })
+            : new StubLexicalRetriever();
+        const vectorProvider = ctx.mongo.uri
+            ? new MongoVectorRetriever({
+                deploymentProfile: ctx.deploymentProfile,
+                uri: ctx.mongo.uri,
+                dbName: ctx.mongo.dbName,
+                connectTimeoutMs: ctx.mongo.connectTimeoutMs
+            })
+            : new StubVectorRetriever();
+        const fusionProvider = new AdaptiveFusionRetriever({
+            supportsNativeFusion: hasNativeFusion(ctx.deploymentProfile),
+            uri: ctx.mongo.uri,
+            dbName: ctx.mongo.dbName,
+            connectTimeoutMs: ctx.mongo.connectTimeoutMs
+        });
+        const engine = new RetrievalEngine(lexicalProvider, vectorProvider, fusionProvider);
+        const result = await engine.retrieve({
+            query: "startup retrieval probe",
+            scopeFilters: {
+                ...(ctx.mongo.uri
+                    ? {
+                        tenant_id: "tenant-demo",
+                        workspace_id: "workspace-alpha"
+                    }
+                    : {
+                        tenant: "bootstrap"
+                    })
+            },
+            topK: 3,
+            profile: ctx.deploymentProfile,
+            preferNativeFusion: Boolean(ctx.mongo.uri)
+        });
+        return {
+            status: "ready",
+            details: {
+                mode: result.mode,
+                degraded: result.degraded,
+                hitCount: result.hits.length,
+                fusionStrategy: result.debug.fusionStrategy,
+                diagnostics: result.diagnostics,
+                providerMode: ctx.mongo.uri ? "mongo" : "stub"
+            }
+        };
+    }
+};

package/dist/modules/stub.js

@@ -0,0 +1,17 @@
+export function createStubModule(config) {
+    return {
+        name: config.name,
+        contractVersion: config.contractVersion,
+        boundaries: config.boundaries,
+        async start(ctx) {
+            return {
+                status: "ready",
+                details: {
+                    deploymentProfile: ctx.deploymentProfile,
+                    startedAt: ctx.startedAt,
+                    note: "module stub initialized"
+                }
+            };
+        }
+    };
+}

package/dist/modules/tool-runtime/index.js

@@ -0,0 +1,30 @@
+import { executeToolRuntimeRequest } from "./service.js";
+export const moduleDefinition = {
+    name: "tool-runtime",
+    contractVersion: "v1",
+    boundaries: ["orchestrator->tool-runtime.v1", "tool-runtime->policy-engine.v1"],
+    async start(ctx) {
+        const sample = executeToolRuntimeRequest({
+            tool_name: "fetch_profile",
+            tool_call_id: "tool-runtime-health-001",
+            params: {
+                user_id: "u-123"
+            },
+            policy_context: {
+                tenant_id: "tenant-demo",
+                workspace_id: "workspace-alpha",
+                deployment_profile: ctx.deploymentProfile
+            }
+        });
+        return {
+            status: sample.ok ? "ready" : "degraded",
+            details: {
+                deploymentProfile: ctx.deploymentProfile,
+                status: sample.response.status,
+                policy: sample.policy,
+                sideEffectRefs: sample.response.side_effect_refs,
+                note: "tool runtime baseline initialized"
+            }
+        };
+    }
+};