@feltdb/core 0.7.4 → 0.8.1

package/dist/module-intent.js

@@ -0,0 +1,230 @@
+import { formatFlowSpec, parseFlowSpec, } from "./flowspec.js";
+import { findFeltDBModules, listFeltDBModules, resolveFeltDBModule, } from "./module.js";
+import { collectApplicationUnderstanding, understandingOwner, } from "./application-understanding.js";
+async function sourceHash(source) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(source.replace(/\r\n/g, "\n")));
+    return `sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+export function resolveModuleIntent(value) {
+    const implement = /^\s*implement\s+([a-z0-9][a-z0-9-]*)\s*[.!]?\s*$/i.exec(value);
+    const finish = /^\s*finish(?:\s+the)?\s+([a-z0-9][a-z0-9-]*)\s+implementation\s*[.!]?\s*$/i.exec(value);
+    let matches = [];
+    let action = "implement";
+    const requested = (implement?.[1] || finish?.[1])?.toLowerCase();
+    if (requested)
+        matches = findFeltDBModules(requested);
+    else {
+        const words = new Set(value.toLowerCase().match(/[a-z0-9-]+/g) ?? []);
+        matches = listFeltDBModules().filter((module) => module.intent_keywords.some((keyword) => words.has(keyword)));
+        action = "extend";
+        if (!matches.length)
+            return undefined;
+    }
+    if (!matches.length)
+        throw new Error(`MODULE_NOT_AVAILABLE: ${requested}. No proposal created. Available modules: ${listFeltDBModules()
+            .map((module) => module.id)
+            .join(", ")}`);
+    if (matches.length > 1)
+        throw new Error(`AMBIGUOUS_MODULE_INTENT: ${requested ?? value}. Candidates: ${matches.map((module) => module.id).join(", ")}`);
+    const module = matches[0];
+    return {
+        action,
+        module: module.id,
+        provider: module.provider,
+        version: module.version,
+        original: value,
+    };
+}
+function applicationAuthorization(module, owner, snapshot) {
+    const ownerPolicy = snapshot.policies.find((value) => value.resource === owner ||
+        value.name === owner ||
+        value.resource === module.placement.primary_application_model);
+    const vocabulary = [ownerPolicy?.write, ownerPolicy?.read].filter((value) => Boolean(value));
+    const management = vocabulary.find((value) => /admin|owner/i.test(value));
+    if (!management && vocabulary.length)
+        throw new Error(`CLARIFICATION_REQUIRED: no compatible ${module.id} management policy for ${owner}`);
+    const subject = management ?? "owner";
+    return module.authorization.map((requirement) => requirement.subject === "owner"
+        ? {
+            ...requirement,
+            subject,
+            implication: `${subject} (${module.placement.primary_application_model}.${module.placement.owner_field} -> ${owner}) may manage ${module.name}`,
+        }
+        : requirement);
+}
+function dependencyStatus(module, snapshot) {
+    const collections = new Set(snapshot.schema.map((value) => value.name));
+    const capabilities = new Set(snapshot.capabilities.map((value) => value.name));
+    return module.dependencies.map((dependency) => {
+        const collection = dependency.any_collections?.find((value) => collections.has(value));
+        const capability = dependency.any_capabilities?.find((value) => capabilities.has(value));
+        const policy = dependency.name === "authentication"
+            ? snapshot.policies.find((value) => [value.read, value.write].some((subject) => subject === "authenticated" || subject?.includes("member")))
+            : undefined;
+        return {
+            name: dependency.name,
+            status: (collection || capability || policy ? "satisfied" : "missing"),
+            evidence: [
+                ...(collection ? [`collection:${collection}`] : []),
+                ...(capability ? [`capability:${capability}`] : []),
+                ...(policy ? [`policy:${policy.name}`] : []),
+            ],
+        };
+    });
+}
+function substitute(type, module, owner, snapshot) {
+    if (type === "$project" || type === "ref $project") {
+        const project = snapshot.schema.find((value) => value.name === "Project")?.name;
+        return project ? type.replace("$project", project) : undefined;
+    }
+    return type.replaceAll("$owner", owner).replaceAll("$module", module.id);
+}
+export function planModuleImplementation(intent, snapshot, currentFlow, understanding) {
+    const module = resolveFeltDBModule({
+        name: intent.module,
+        provider: intent.provider,
+        version: intent.version,
+    });
+    const spec = parseFlowSpec(currentFlow);
+    const owner = understandingOwner(understanding, module);
+    if (!owner)
+        throw new Error(`CLARIFICATION_REQUIRED: ${module.placement.owner_claim}`);
+    const alreadyInstalled = Boolean(spec.modules?.some((value) => value.name === module.id));
+    const pattern = module.patterns.find((value) => value.owner_candidates.includes(owner));
+    if (!pattern)
+        throw new Error(`CLARIFICATION_REQUIRED: ${module.placement.owner_claim}=${owner} is unsupported by ${module.id}`);
+    const applicationModels = (intent.action === "extend" && module.extension_application_models?.length
+        ? module.extension_application_models
+        : pattern.application_models).map((value) => ({
+        ...value,
+        fields: value.fields
+            .map((field) => ({
+            ...field,
+            type: substitute(field.type, module, owner, snapshot),
+        }))
+            .filter((field) => Boolean(field.type)),
+    }));
+    const relationships = applicationModels.flatMap((model) => model.fields
+        .filter((field) => field.type.startsWith("ref "))
+        .map((field) => `${model.name}.${field.name} -> ${field.type.slice(4)}`));
+    const implementedEvents = new Set(spec.triggers.map((value) => value.event));
+    const implementedWorkflows = new Set(spec.workflows.map((value) => value.name));
+    const dependencies = dependencyStatus(module, snapshot);
+    const missing = dependencies.filter((value) => value.status === "missing");
+    if (missing.length)
+        throw new Error(`MISSING_MODULE_DEPENDENCY: ${missing.map((value) => value.name).join(", ")}`);
+    return {
+        intent,
+        module,
+        alreadyInstalled,
+        owner,
+        ownerClaim: module.placement.owner_claim,
+        primaryApplicationModel: module.placement.primary_application_model,
+        applicationModels,
+        relationships,
+        events: module.reconciliation
+            .map((value) => value.event)
+            .filter((value) => !implementedEvents.has(value)),
+        workflows: module.reconciliation
+            .map((value) => value.workflow)
+            .filter((value) => !implementedWorkflows.has(value)),
+        capabilities: [...module.capabilities],
+        authorization: applicationAuthorization(module, owner, snapshot),
+        configuration: module.configuration.map((value) => value.name),
+        secrets: module.secrets.map((value) => value.name),
+        dependencies,
+        stateFlow: module.reconciliation[0]
+            ? [
+                module.reconciliation[0].event,
+                module.reconciliation[0].workflow,
+                ...module.reconciliation[0].writes,
+            ]
+            : [],
+        warnings: module.validation.map((value) => `Required: ${value}`),
+    };
+}
+function addCollection(spec, collection) {
+    if (!spec.collections.some((value) => value.name === collection.name))
+        spec.collections.push(collection);
+}
+export async function createModuleImplementationProposal(input) {
+    const resolved = resolveModuleIntent(input.intent);
+    if (!resolved)
+        throw new Error("NOT_A_MODULE_INTENT");
+    const understanding = await collectApplicationUnderstanding({
+        intent: input.intent,
+        snapshot: input.snapshot,
+        currentFlow: input.currentFlow,
+        moduleIntent: resolved,
+        observations: input.observations,
+    });
+    const plan = planModuleImplementation(resolved, input.snapshot, input.currentFlow, understanding);
+    const spec = parseFlowSpec(input.currentFlow);
+    if (resolved.action === "extend" && !plan.alreadyInstalled)
+        throw new Error(`MODULE_NOT_INSTALLED: ${plan.module.id}. Run implement ${plan.module.id} first.`);
+    if (!spec.modules?.some((value) => value.name === plan.module.id))
+        spec.modules.push({
+            name: plan.module.id,
+            provider: plan.module.provider,
+            version: plan.module.version,
+        });
+    for (const model of plan.applicationModels)
+        addCollection(spec, {
+            name: model.name,
+            fields: model.fields.map((field) => ({
+                name: field.name,
+                type: field.type,
+                optional: Boolean(field.optional),
+            })),
+            indexes: [],
+        });
+    for (const reconciliation of plan.module.reconciliation) {
+        if (!spec.workflows.some((value) => value.name === reconciliation.workflow)) {
+            const readCapability = plan.module.capabilities.find((value) => value.endsWith(".read"));
+            spec.workflows.push({
+                name: reconciliation.workflow,
+                parameters: "",
+                steps: [
+                    {
+                        name: "reconcile",
+                        statements: [
+                            ...reconciliation.reads.map((value) => `read ${value}`),
+                            ...reconciliation.writes.map((value) => `write ${value}`),
+                            ...(readCapability ? [`capability ${readCapability}`] : []),
+                        ],
+                    },
+                ],
+            });
+        }
+        if (!spec.triggers.some((value) => value.event === reconciliation.event))
+            spec.triggers.push({
+                event: reconciliation.event,
+                statements: [`run ${reconciliation.workflow}`],
+            });
+    }
+    if (!spec.policies.some((value) => value.name === plan.primaryApplicationModel))
+        spec.policies.push({
+            name: plan.primaryApplicationModel,
+            statements: ["read: owner", "write: owner"],
+        });
+    const prefix = resolved.action === "extend"
+        ? "Extend"
+        : plan.alreadyInstalled
+            ? "Complete"
+            : "Implement";
+    return {
+        baseContractHash: input.snapshot.contract_hash,
+        baseFlowHash: await sourceHash(input.currentFlow),
+        proposedFlow: formatFlowSpec(spec),
+        summary: `${prefix} ${plan.module.name}`,
+        changes: [
+            ...plan.applicationModels.map((value) => `${value.name} (${value.ownership})`),
+            ...plan.relationships,
+            ...plan.workflows,
+            ...plan.capabilities,
+        ],
+        warnings: plan.warnings,
+        implementation: plan,
+        understanding,
+    };
+}

package/dist/module.d.ts

@@ -0,0 +1,105 @@
+export type FeltDBModuleOwnership = "external-authoritative" | "application-authoritative" | "derived" | "synchronized";
+export interface FeltDBModuleField {
+    name: string;
+    type: string;
+    optional?: boolean;
+    immutable?: boolean;
+    externally_owned?: boolean;
+    application_readable?: boolean;
+}
+export interface FeltDBModuleModel {
+    name: string;
+    authority: "external" | "application";
+    ownership: FeltDBModuleOwnership;
+    fields: FeltDBModuleField[];
+}
+export interface FeltDBModuleRelationship {
+    from: string;
+    to: string;
+    kind: "one" | "many";
+}
+export interface FeltDBModuleRequirement {
+    name: string;
+    required: boolean;
+    environments?: string[];
+    description: string;
+    visibility?: "server" | "browser";
+}
+export interface FeltDBModuleApplicationField {
+    name: string;
+    type: string;
+    optional?: boolean;
+}
+export interface FeltDBModulePattern {
+    name: string;
+    when: string;
+    owner_candidates: string[];
+    application_models: Array<{
+        name: string;
+        ownership: FeltDBModuleOwnership;
+        purpose: string;
+        fields: FeltDBModuleApplicationField[];
+    }>;
+}
+export interface FeltDBModuleReconciliation {
+    event: string;
+    workflow: string;
+    reads: string[];
+    writes: string[];
+    outcome: string;
+}
+export interface FeltDBModuleDependency {
+    name: string;
+    description: string;
+    any_collections?: string[];
+    any_capabilities?: string[];
+}
+export interface FeltDBModuleSourceArtifact {
+    path: string;
+    role: string;
+    purpose: string;
+}
+export interface FeltDBModuleDefinition {
+    id: string;
+    name: string;
+    version: string;
+    provider: string;
+    compatibility: string[];
+    intent_keywords: string[];
+    models: FeltDBModuleModel[];
+    relationships: FeltDBModuleRelationship[];
+    events: string[];
+    capabilities: string[];
+    workflows: string[];
+    configuration: FeltDBModuleRequirement[];
+    secrets: FeltDBModuleRequirement[];
+    validation: string[];
+    dependencies: FeltDBModuleDependency[];
+    authorization: Array<{
+        capability: string;
+        subject: string;
+        implication: string;
+    }>;
+    patterns: FeltDBModulePattern[];
+    reconciliation: FeltDBModuleReconciliation[];
+    placement: {
+        owner_claim: string;
+        primary_application_model: string;
+        owner_field: string;
+    };
+    source_artifacts: FeltDBModuleSourceArtifact[];
+    extension_application_models?: FeltDBModulePattern["application_models"];
+}
+export interface FlowModuleDeclaration {
+    name: string;
+    provider: string;
+    version?: string;
+}
+export declare function validateFeltDBModule(module: FeltDBModuleDefinition): string[];
+export declare function registerFeltDBModule(module: FeltDBModuleDefinition): () => void;
+export declare function listFeltDBModules(): FeltDBModuleDefinition[];
+export declare function resolveFeltDBModule(declaration: FlowModuleDeclaration): FeltDBModuleDefinition;
+export declare function findFeltDBModules(query: string): FeltDBModuleDefinition[];
+export declare function resolveFeltDBModules(declarations?: FlowModuleDeclaration[]): FeltDBModuleDefinition[];
+export declare function validateResolvedModules(modules: FeltDBModuleDefinition[], environment?: string): string[];
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"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"}