@glubean/sdk 0.1.39 → 0.2.0

package/dist/contract-core.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Protocol-agnostic contract core.
+ *
+ * Provides:
+ *   - Adapter registry (`_adapters`)
+ *   - `contract.register(protocol, adapter)` — plugin extension point
+ *   - `contract[protocol](id, spec)` dispatcher — validates 1:1 case keys,
+ *     invokes adapter.execute per case, registers tests + ContractRegistryMeta
+ *   - `contract.flow(id)` — protocol-agnostic FlowBuilder
+ *   - `runFlow(flow, ctx)` — core flow execution helper (Rule 1/2 teardown)
+ *   - `normalizeFlow(runtime)` — Runtime → ExtractedFlowProjection
+ *   - Permissive Proxy tracer for `compute` nodes (best-effort reads/writes)
+ *
+ * HTTP is NOT handled here — it registers itself in `./contract-http/`.
+ * This file has zero HTTP-specific code.
+ *
+ * See:
+ *   - `internal/40-discovery/proposals/contract-generics-complete.md` v5
+ *   - `internal/40-discovery/proposals/contract-flow.md` v9
+ */
+import type { TestContext } from "./types.js";
+import type { ContractProtocolAdapter, ExtractedFlowProjection, FieldMapping, FlowBuilder, FlowContract, FlowMeta, RuntimeFlowProjection } from "./contract-types.js";
+/** Internal accessor for plugins / downstream (scanner, runner). */
+export declare function getAdapter(protocol: string): ContractProtocolAdapter<any, any, any, any, any> | undefined;
+/**
+ * Register an adapter. Called by built-in HTTP adapter on SDK load, and by
+ * external adapter plugins (`@glubean/contract-grpc` etc.) on their import.
+ */
+declare function register<Spec, RuntimeSchemas = unknown, RuntimeMeta = unknown, SafeSchemas = unknown, SafeMeta = unknown>(protocol: string, adapter: ContractProtocolAdapter<Spec, RuntimeSchemas, RuntimeMeta, SafeSchemas, SafeMeta>): void;
+type ContractNamespace = {
+    register: typeof register;
+    flow: typeof flow;
+    [protocol: string]: unknown;
+};
+export declare const contract: ContractNamespace;
+/**
+ * Protocol-agnostic flow builder. See contract-flow.md v9 §4.1.
+ */
+export declare function flow(idOrMeta: string | FlowMeta): FlowBuilder<unknown>;
+/**
+ * Core flow execution helper. Implements the Rule 1 / Rule 2 teardown
+ * semantics from contract-flow.md §7.
+ */
+export declare function runFlow<State>(flowContract: FlowContract<State>, ctx: TestContext): Promise<void>;
+/**
+ * Normalize a RuntimeFlowProjection to JSON-safe ExtractedFlowProjection.
+ * Runs Proxy dry-run of lens functions to extract FieldMappings.
+ *
+ * Lens purity is enforced here: if a `step.bindings.in` or `.out` lens
+ * violates purity (method call, `new`, etc.), `LensPurityError` is thrown
+ * with step context so the author sees which step needs fixing.
+ */
+export declare function normalizeFlow<State>(runtime: RuntimeFlowProjection<State> & {
+    id: string;
+}): ExtractedFlowProjection;
+/**
+ * Run a pure lens `fn: (state) => output` with a tracing Proxy, extracting
+ * FieldMappings from state paths to output paths.
+ *
+ * Pure-lens enforcement: method calls, `new`, and coercion on the state
+ * proxy raise `LensPurityError`. Errors are **not** swallowed — the caller
+ * (typically `normalizeFlow`) wraps them with step context and re-throws,
+ * so authors see the failure at flow build time rather than silently
+ * losing projection data.
+ */
+export declare function extractMappings(fn: (state: any) => any): FieldMapping[];
+/**
+ * Extract FieldMappings from `out: (state, response) => newState`.
+ * Same purity contract as `extractMappings`.
+ */
+export declare function extractMappingsOut(fn: (state: any, response: any) => any): FieldMapping[];
+/**
+ * Raised by the strict lens Proxy when a user lens fn attempts an operation
+ * that breaks the "pure field access + repack" contract. Caught and re-
+ * thrown with step context by `normalizeFlow`.
+ */
+export declare class LensPurityError extends Error {
+    readonly path: string;
+    readonly operation: string;
+    constructor(path: string, operation: string);
+}
+/**
+ * Trace a `compute` fn to extract top-level reads + writes.
+ *
+ * Compute allows arbitrary sync TS (template literals, method calls, .map()),
+ * so the Proxy must be permissive: respond to primitive coercion, swallow
+ * method calls, etc. We only record top-level property access paths.
+ *
+ * See contract-flow.md §4.1.1 for design + known limitations.
+ */
+export declare function traceComputeFn(fn: (state: any) => any): {
+    reads: string[];
+    writes: string[];
+};
+export {};
+//# sourceMappingURL=contract-core.d.ts.map

package/dist/contract-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-core.d.ts","sourceRoot":"","sources":["../src/contract-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAQ,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAEV,uBAAuB,EAGvB,uBAAuB,EAEvB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,QAAQ,EAKR,qBAAqB,EAEtB,MAAM,qBAAqB,CAAC;AAS7B,oEAAoE;AACpE,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,GACf,uBAAuB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS,CAE9D;AAYD;;;GAGG;AACH,iBAAS,QAAQ,CACf,IAAI,EACJ,cAAc,GAAG,OAAO,EACxB,WAAW,GAAG,OAAO,EACrB,WAAW,GAAG,OAAO,EACrB,QAAQ,GAAG,OAAO,EAElB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,uBAAuB,CAAC,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAC,GACzF,IAAI,CAgBN;AA6OD,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,IAAI,EAAE,OAAO,IAAI,CAAC;IAClB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7B,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,iBAGtB,CAAC;AAMF;;GAEG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAqJtE;AAyBD;;;GAGG;AACH,wBAAsB,OAAO,CAAC,KAAK,EACjC,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC,EACjC,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,IAAI,CAAC,CAuEf;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EACjC,OAAO,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GACrD,uBAAuB,CAoEzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,GAAG,YAAY,EAAE,CAIvE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,KAAK,GAAG,GACrC,YAAY,EAAE,CAMhB;AAkED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBACf,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAY5C;AAiDD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,GACtB;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAavC"}