@appport/sdk 1.0.2 → 1.1.1

package/dist/provider-lifecycle.js

@@ -0,0 +1,314 @@
+/**
+ * Provider lifecycle and migration primitives.
+ *
+ * A capability contract is stable; the providers that fulfil it are not. These
+ * helpers make that difference executable: a provider is registered against a
+ * contract, becomes eligible, may be activated for resolution, and can be
+ * drained, revoked and retired without the consumer ever learning which
+ * implementation served it.
+ *
+ * The primitives are deliberately language, runtime and surface agnostic. A
+ * provider is a provider identifier plus the contract it declares; nothing here
+ * knows about COBOL, HTTP, Wasm or any other implementation detail. AppBoundry
+ * owns lifecycle and resolution, AppPort owns the capability contract.
+ */
+/** The only state in which a provider may be selected by resolution. */
+export const RESOLVABLE_PROVIDER_STATE = "active";
+const LEGAL_TRANSITIONS = {
+    registered: ["eligible", "revoked", "retired"],
+    eligible: ["active", "revoked", "retired"],
+    active: ["draining", "revoked", "eligible"],
+    draining: ["revoked", "retired"],
+    revoked: ["retired"],
+    retired: []
+};
+/** Raised when a lifecycle operation is not permitted. */
+export class ProviderLifecycleError extends Error {
+    providerId;
+    constructor(message, providerId) {
+        super(message);
+        this.providerId = providerId;
+        this.name = "ProviderLifecycleError";
+    }
+}
+/** Raised when a migration cannot be performed. No state changes when it is thrown. */
+export class ProviderMigrationRejected extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "ProviderMigrationRejected";
+    }
+}
+/** Recorded when a transition did not itself execute the capability. */
+export const NOT_OBSERVED = "not_observed";
+function observation(input) {
+    return (input ?? {
+        authorization: NOT_OBSERVED,
+        eligibility: NOT_OBSERVED,
+        resolution: NOT_OBSERVED,
+        materialization: NOT_OBSERVED,
+        execution: NOT_OBSERVED
+    });
+}
+/**
+ * The authority for provider lifecycle state.
+ *
+ * Resolution must consult {@link ProviderLifecycleRegistry.resolvable} so that
+ * eligibility, revocation and retirement affect real provider selection instead
+ * of being descriptive metadata.
+ */
+export class ProviderLifecycleRegistry {
+    now;
+    #records = new Map();
+    #evidence = [];
+    #sequence = 0;
+    constructor(now = () => new Date()) {
+        this.now = now;
+    }
+    /**
+     * Registers a provider in the `registered` state.
+     *
+     * Registering an identifier that is currently retired is the explicit new
+     * registration required to bring a retired provider back into service; it
+     * always produces a new `registrationId`.
+     */
+    register(registration) {
+        const existing = this.#records.get(registration.providerId);
+        if (existing && existing.state !== "retired") {
+            throw new ProviderLifecycleError(`provider ${registration.providerId} is already registered as ${existing.state}`, registration.providerId);
+        }
+        const record = {
+            ...registration,
+            state: "registered",
+            registrationId: `reg_${registration.providerId}_${++this.#sequence}`
+        };
+        this.#records.set(registration.providerId, record);
+        this.#record(record, existing?.state ?? "registered", {});
+        return record;
+    }
+    /** The provider satisfies the contract requirements for its capability. */
+    markEligible(providerId, context = {}) {
+        return this.#transition(providerId, "eligible", context);
+    }
+    /** The provider may now be selected by resolution. */
+    activate(providerId, context = {}) {
+        return this.#transition(providerId, "active", context);
+    }
+    /** The provider is leaving service; new resolution must not select it. */
+    drain(providerId, context = {}) {
+        return this.#transition(providerId, "draining", context);
+    }
+    /** The provider is no longer eligible for new requests. */
+    revoke(providerId, context = {}) {
+        return this.#transition(providerId, "revoked", context);
+    }
+    /** The provider registration is removed from the provider set, permanently. */
+    retire(providerId, context = {}) {
+        return this.#transition(providerId, "retired", context);
+    }
+    /** The current record, or `undefined` when the provider was never registered. */
+    record(providerId) {
+        return this.#records.get(providerId);
+    }
+    /** The current state, or `undefined` when the provider was never registered. */
+    state(providerId) {
+        return this.#records.get(providerId)?.state;
+    }
+    /** Every known registration, in registration order. */
+    records() {
+        return [...this.#records.values()];
+    }
+    /** Providers AppBoundry may currently select for `capability`. */
+    resolvable(capability) {
+        return this.records().filter((record) => record.capability === capability && record.state === RESOLVABLE_PROVIDER_STATE);
+    }
+    /** Whether resolution may currently select `providerId`. */
+    isResolvable(providerId) {
+        return this.#records.get(providerId)?.state === RESOLVABLE_PROVIDER_STATE;
+    }
+    /** Every transition recorded so far, oldest first. */
+    evidence() {
+        return [...this.#evidence];
+    }
+    /** Records evidence for an execution that resolved to `providerId`. */
+    recordExecution(providerId, observed) {
+        const record = this.#require(providerId);
+        return this.#record(record, record.state, { observed });
+    }
+    #transition(providerId, next, context) {
+        const record = this.#require(providerId);
+        if (!LEGAL_TRANSITIONS[record.state].includes(next)) {
+            throw new ProviderLifecycleError(`provider ${providerId} cannot move from ${record.state} to ${next}`, providerId);
+        }
+        const updated = { ...record, state: next };
+        this.#records.set(providerId, updated);
+        this.#record(updated, record.state, context);
+        return updated;
+    }
+    #require(providerId) {
+        const record = this.#records.get(providerId);
+        if (!record)
+            throw new ProviderLifecycleError(`provider ${providerId} is not registered`, providerId);
+        return record;
+    }
+    #record(record, previousState, context) {
+        const observed = observation(context.observed);
+        const evidence = {
+            capability: record.capability,
+            contract: record.contract,
+            provider: record.providerId,
+            providerState: record.state,
+            previousProviderState: previousState,
+            ...(context.previousProvider ? { previousProvider: context.previousProvider } : {}),
+            ...(context.replacementProvider ? { replacementProvider: context.replacementProvider } : {}),
+            ...(context.migrationId ? { migrationId: context.migrationId } : {}),
+            ...observed,
+            environment: record.environment ?? "unspecified",
+            timestamp: this.now().toISOString(),
+            evidenceId: `evd_lifecycle_${record.providerId}_${++this.#sequence}`
+        };
+        this.#evidence.push(evidence);
+        return evidence;
+    }
+}
+let migrationSequence = 0;
+/**
+ * Moves a capability from one provider to another as a single platform
+ * operation.
+ *
+ * The migration is validated in full before any state changes, so a rejected
+ * migration leaves the currently active provider untouched. On success the
+ * retiring provider is drained, revoked and retired, and the replacement is
+ * activated. The consumer is never involved: it keeps requesting the same
+ * capability contract.
+ */
+export function migrateProvider(registry, input) {
+    const retiring = registry.record(input.retiringProvider);
+    const replacement = registry.record(input.replacementProvider);
+    if (!retiring) {
+        throw new ProviderMigrationRejected(`retiring provider ${input.retiringProvider} is not registered`, "retiring_provider_unknown");
+    }
+    if (!replacement) {
+        throw new ProviderMigrationRejected(`replacement provider ${input.replacementProvider} is not registered`, "replacement_provider_unknown");
+    }
+    if (retiring.capability !== input.capability || retiring.contract !== input.contract) {
+        throw new ProviderMigrationRejected(`retiring provider ${retiring.providerId} does not satisfy ${input.capability}/${input.contract}`, "retiring_provider_contract_mismatch");
+    }
+    if (retiring.state !== RESOLVABLE_PROVIDER_STATE) {
+        throw new ProviderMigrationRejected(`retiring provider ${retiring.providerId} is ${retiring.state}, not ${RESOLVABLE_PROVIDER_STATE}`, "retiring_provider_not_active");
+    }
+    if (replacement.capability !== input.capability || replacement.contract !== input.contract) {
+        throw new ProviderMigrationRejected(`replacement provider ${replacement.providerId} does not satisfy ${input.capability}/${input.contract}`, "replacement_contract_mismatch");
+    }
+    if (replacement.contractFingerprint !== retiring.contractFingerprint) {
+        throw new ProviderMigrationRejected(`replacement provider ${replacement.providerId} declares a different contract fingerprint`, "replacement_contract_fingerprint_mismatch");
+    }
+    if (replacement.state !== "eligible" && replacement.state !== "active") {
+        throw new ProviderMigrationRejected(`replacement provider ${replacement.providerId} is ${replacement.state} and is not eligible`, "replacement_not_eligible");
+    }
+    if (input.consumerContract !== input.capability) {
+        throw new ProviderMigrationRejected(`migration would change the consumer contract from ${input.consumerContract} to ${input.capability}`, "consumer_contract_changed");
+    }
+    const migrationId = input.migrationId ?? `mig_${input.capability.replace(/[^a-z0-9]+/gi, "_")}_${++migrationSequence}`;
+    const context = {
+        migrationId,
+        previousProvider: retiring.providerId,
+        replacementProvider: replacement.providerId
+    };
+    registry.drain(retiring.providerId, context);
+    registry.revoke(retiring.providerId, context);
+    registry.retire(retiring.providerId, context);
+    if (replacement.state === "eligible")
+        registry.activate(replacement.providerId, context);
+    return {
+        migrationId,
+        capability: input.capability,
+        contract: input.contract,
+        retiringProvider: retiring.providerId,
+        replacementProvider: replacement.providerId,
+        retiringProviderState: registry.state(retiring.providerId),
+        replacementProviderState: registry.state(replacement.providerId),
+        consumerContract: input.consumerContract,
+        consumerSourceHash: input.consumerSourceHash,
+        evidence: registry.evidence().filter((entry) => entry.migrationId === migrationId)
+    };
+}
+/**
+ * Fails when a request resolved to a provider AppBoundry had already declared
+ * ineligible.
+ */
+export function assertResolutionInvariant(records) {
+    for (const record of records) {
+        if (record.providerStateAtResolution !== RESOLVABLE_PROVIDER_STATE) {
+            throw new Error(`request ${record.requestId} resolved to ${record.resolvedProvider} in state ${record.providerStateAtResolution}`);
+        }
+    }
+}
+/** Builds the machine-readable report from what the harness observed. */
+export function createProviderMigrationReport(observation) {
+    const passed = observation.consumerContractUnchanged &&
+        observation.consumerSourceUnchanged &&
+        observation.before.execution === "pass" &&
+        observation.after.execution === "pass" &&
+        observation.retirement.legacyProcessStopped &&
+        observation.retirement.legacyArtifactUnavailable &&
+        observation.retirement.directInvocationFailed &&
+        observation.noEligibleProvider.verified &&
+        observation.restoration.verified &&
+        observation.invalidMigration.rejected &&
+        observation.resolutions.every((record) => record.providerStateAtResolution === RESOLVABLE_PROVIDER_STATE && record.executionResult !== "not_observed");
+    return {
+        title: "AppBoundry Provider Migration Proof",
+        generatedBy: "appport.providerMigrationHarness",
+        result: passed ? "pass" : "fail",
+        ...observation
+    };
+}
+function statusOf(flag, pass, fail) {
+    return flag ? pass : fail;
+}
+/** Formats the human-readable migration proof trace. */
+export function formatProviderMigrationTrace(report) {
+    const { migration } = report;
+    const lines = [
+        report.title,
+        `${report.capability}`,
+        `Contract: ${report.contract}`,
+        "Before",
+        `  Provider: ${report.before.provider}`,
+        `  Environment: ${report.before.environment ?? "unspecified"}`,
+        `  State:    ${report.before.state.toUpperCase()}`,
+        `  Execution: ${report.before.execution.toUpperCase()}`,
+        "Migration",
+        `  Migration ID: ${migration.migrationId}`,
+        `  ${migration.retiringProvider}: ACTIVE → DRAINING → REVOKED → ${migration.retiringProviderState.toUpperCase()}`,
+        `  ${migration.replacementProvider}: ELIGIBLE → ${migration.replacementProviderState.toUpperCase()}`,
+        "After",
+        `  Provider: ${report.after.provider}`,
+        `  Environment: ${report.after.environment ?? "unspecified"}`,
+        `  State:    ${report.after.state.toUpperCase()}`,
+        `  Execution: ${report.after.execution.toUpperCase()}`,
+        `Consumer contract: ${statusOf(report.consumerContractUnchanged, "UNCHANGED", "CHANGED")}`,
+        `Consumer source:   ${statusOf(report.consumerSourceUnchanged, "UNCHANGED", "CHANGED")}`,
+        "Physical retirement",
+        `  Legacy process:    ${statusOf(report.retirement.legacyProcessStopped, "STOPPED", "RUNNING")}`,
+        `  Legacy artifact:   ${statusOf(report.retirement.legacyArtifactUnavailable, "REMOVED", "PRESENT")}`,
+        `  Direct invocation: ${statusOf(report.retirement.directInvocationFailed, "FAILED AS EXPECTED", "SUCCEEDED")}`,
+        "No-provider test",
+        `  Resolution: ${report.noEligibleProvider.code}`,
+        `  ${statusOf(report.noEligibleProvider.verified, "VERIFIED", "NOT VERIFIED")}`,
+        "Restoration",
+        `  Provider: ${report.restoration.provider}`,
+        `  ${statusOf(report.restoration.verified, "VERIFIED", "NOT VERIFIED")}`,
+        "Invalid replacement",
+        `  ${statusOf(report.invalidMigration.rejected, "REJECTED", "ACCEPTED")} (${report.invalidMigration.reason})`,
+        "Resolution during migration"
+    ];
+    for (const record of report.resolutions) {
+        lines.push(`  ${record.requestId} → ${record.resolvedProvider} [${record.providerStateAtResolution.toUpperCase()}] ${record.executionResult.toUpperCase()} ${record.evidenceId}`);
+    }
+    lines.push(`RESULT: ${report.result.toUpperCase()}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=provider-lifecycle.js.map

package/dist/provider-lifecycle.js.map

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

package/dist/resolution-policy.d.ts

@@ -0,0 +1,81 @@
+import { type ProviderLifecycleRegistry, type ProviderLifecycleState, type ProviderResolutionRecord } from "./provider-lifecycle.js";
+export declare const NO_ELIGIBLE_PROVIDER: "appboundry.NO_ELIGIBLE_PROVIDER";
+export interface ResolutionPolicyProvider {
+    readonly provider: string;
+    readonly priority: number;
+    readonly environments?: readonly string[];
+    readonly attributes?: Readonly<Record<string, string>>;
+}
+export interface ResolutionPolicyDefinition {
+    readonly policyId: string;
+    readonly policyVersion: string | number;
+    readonly capability: string;
+    readonly contract: string;
+    readonly providers: readonly ResolutionPolicyProvider[];
+}
+export interface ResolutionPolicy extends ResolutionPolicyDefinition {
+    readonly policyVersion: string;
+}
+export declare class PolicyEvaluationError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare function defineResolutionPolicy(definition: ResolutionPolicyDefinition): ResolutionPolicy;
+export interface PolicyCandidate {
+    readonly providerId: string;
+    readonly capability: string;
+    readonly contract: string;
+    readonly attributes?: Readonly<Record<string, string>>;
+}
+export interface PolicyAuthorizationDecision {
+    readonly outcome: "allow" | "deny";
+    readonly reason?: string;
+}
+export interface PolicyResolutionRequest {
+    readonly requestId: string;
+    readonly capability: string;
+    readonly contract: string;
+    readonly environment?: string;
+    readonly candidates: readonly PolicyCandidate[];
+    readonly lifecycle: ProviderLifecycleRegistry;
+    readonly authorize: (candidate: PolicyCandidate) => PolicyAuthorizationDecision | Promise<PolicyAuthorizationDecision>;
+    readonly now?: () => Date;
+}
+export type PolicyExclusionReason = "NOT_IN_POLICY" | "CAPABILITY_MISMATCH" | "CONTRACT_MISMATCH" | "REGISTERED" | "ELIGIBLE" | "DRAINING" | "REVOKED" | "RETIRED" | "UNREGISTERED" | "ENVIRONMENT_MISMATCH" | "ATTRIBUTE_MISMATCH" | "UNAUTHORIZED";
+export interface PolicyCandidateEvidence {
+    readonly provider: string;
+    readonly priority?: number;
+    readonly state: ProviderLifecycleState | "unregistered";
+}
+export interface PolicyExcludedProvider extends PolicyCandidateEvidence {
+    readonly reasons: readonly PolicyExclusionReason[];
+}
+export interface PolicyResolutionEvidence extends ProviderResolutionRecord {
+    readonly policyId: string;
+    readonly policyVersion: string;
+    readonly candidateProviders: readonly PolicyCandidateEvidence[];
+    readonly eligibleProviders: readonly PolicyCandidateEvidence[];
+    readonly excludedProviders: readonly PolicyExcludedProvider[];
+    readonly excludedReasons: Readonly<Record<string, readonly PolicyExclusionReason[]>>;
+    readonly selectedProvider?: string;
+    readonly authorization: "allowed" | "denied" | "not_observed";
+    readonly eligibility: "eligible" | "ineligible";
+    readonly resolution: "resolved" | typeof NO_ELIGIBLE_PROVIDER;
+    readonly materialization: string;
+    readonly execution: "success" | "failure" | "not_observed";
+    readonly timestamp: string;
+}
+export type PolicyDecision = {
+    readonly kind: "resolved";
+    readonly selected: PolicyCandidate;
+    readonly evidence: PolicyResolutionEvidence;
+} | {
+    readonly kind: "unresolved";
+    readonly code: typeof NO_ELIGIBLE_PROVIDER;
+    readonly evidence: PolicyResolutionEvidence;
+};
+/** Authorization and lifecycle are evaluated before policy priority is applied. */
+export declare function resolveWithPolicy(policy: ResolutionPolicy, request: PolicyResolutionRequest): Promise<PolicyDecision>;
+/** Produces a new immutable evidence record; the resolution snapshot is never rewritten. */
+export declare function recordPolicyExecution(evidence: PolicyResolutionEvidence, result: "success" | "failure", materialization?: string): PolicyResolutionEvidence;
+//# sourceMappingURL=resolution-policy.d.ts.map

package/dist/resolution-policy.d.ts.map

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

package/dist/resolution-policy.js

@@ -0,0 +1,131 @@
+import { NOT_OBSERVED, RESOLVABLE_PROVIDER_STATE } from "./provider-lifecycle.js";
+export const NO_ELIGIBLE_PROVIDER = "appboundry.NO_ELIGIBLE_PROVIDER";
+export class PolicyEvaluationError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "PolicyEvaluationError";
+    }
+}
+export function defineResolutionPolicy(definition) {
+    if (!definition.policyId.trim())
+        throw new PolicyEvaluationError("policyId is required", "INVALID_POLICY_ID");
+    const policyVersion = String(definition.policyVersion).trim();
+    if (!policyVersion)
+        throw new PolicyEvaluationError("policyVersion is required", "INVALID_POLICY_VERSION");
+    if (!definition.capability.trim() || !definition.contract.trim()) {
+        throw new PolicyEvaluationError("capability and contract are required", "INVALID_POLICY_CONTRACT");
+    }
+    const seen = new Set();
+    for (const entry of definition.providers) {
+        if (!entry.provider.trim() || !Number.isFinite(entry.priority)) {
+            throw new PolicyEvaluationError("provider identity and finite priority are required", "INVALID_PROVIDER_PREFERENCE");
+        }
+        if (seen.has(entry.provider)) {
+            throw new PolicyEvaluationError(`provider ${entry.provider} appears more than once`, "DUPLICATE_PROVIDER");
+        }
+        seen.add(entry.provider);
+    }
+    return Object.freeze({ ...definition, policyVersion, providers: Object.freeze([...definition.providers]) });
+}
+/** Authorization and lifecycle are evaluated before policy priority is applied. */
+export async function resolveWithPolicy(policy, request) {
+    if (request.capability !== policy.capability || request.contract !== policy.contract) {
+        throw new PolicyEvaluationError("policy cannot alter the requested capability contract", "POLICY_REQUEST_MISMATCH");
+    }
+    const preferences = new Map(policy.providers.map((entry) => [entry.provider, entry]));
+    const candidates = [];
+    const eligible = [];
+    const excluded = [];
+    for (const candidate of request.candidates) {
+        const preference = preferences.get(candidate.providerId);
+        const state = request.lifecycle.state(candidate.providerId) ?? "unregistered";
+        const evidence = {
+            provider: candidate.providerId,
+            ...(preference ? { priority: preference.priority } : {}),
+            state
+        };
+        candidates.push(evidence);
+        const reasons = [];
+        if (!preference)
+            reasons.push("NOT_IN_POLICY");
+        if (candidate.capability !== request.capability)
+            reasons.push("CAPABILITY_MISMATCH");
+        if (candidate.contract !== request.contract)
+            reasons.push("CONTRACT_MISMATCH");
+        if (state !== RESOLVABLE_PROVIDER_STATE)
+            reasons.push(state === "unregistered" ? "UNREGISTERED" : state.toUpperCase());
+        if (preference?.environments && (!request.environment || !preference.environments.includes(request.environment)))
+            reasons.push("ENVIRONMENT_MISMATCH");
+        if (preference?.attributes && !matchesAttributes(preference.attributes, candidate.attributes))
+            reasons.push("ATTRIBUTE_MISMATCH");
+        if (reasons.length === 0) {
+            const authorization = await request.authorize(candidate);
+            if (authorization.outcome === "deny")
+                reasons.push("UNAUTHORIZED");
+        }
+        if (reasons.length)
+            excluded.push({ ...evidence, reasons });
+        else
+            eligible.push({ candidate, evidence });
+    }
+    eligible.sort((left, right) => (right.evidence.priority ?? 0) - (left.evidence.priority ?? 0) || left.candidate.providerId.localeCompare(right.candidate.providerId));
+    const selected = eligible[0];
+    const timestamp = (request.now ?? (() => new Date()))().toISOString();
+    const base = {
+        requestId: request.requestId,
+        capability: request.capability,
+        contract: request.contract,
+        policyId: policy.policyId,
+        policyVersion: policy.policyVersion,
+        candidateProviders: candidates,
+        eligibleProviders: eligible.map((entry) => entry.evidence),
+        excludedProviders: excluded,
+        excludedReasons: Object.fromEntries(excluded.map((entry) => [entry.provider, entry.reasons])),
+        materialization: NOT_OBSERVED,
+        execution: NOT_OBSERVED,
+        executionResult: "not_observed",
+        timestamp
+    };
+    if (!selected) {
+        return {
+            kind: "unresolved",
+            code: NO_ELIGIBLE_PROVIDER,
+            evidence: {
+                ...base,
+                resolvedProvider: NO_ELIGIBLE_PROVIDER,
+                providerStateAtResolution: "registered",
+                authorization: candidates.length ? "denied" : "not_observed",
+                eligibility: "ineligible",
+                resolution: NO_ELIGIBLE_PROVIDER,
+                evidenceId: evidenceId(request.requestId, policy, NO_ELIGIBLE_PROVIDER)
+            }
+        };
+    }
+    return {
+        kind: "resolved",
+        selected: selected.candidate,
+        evidence: {
+            ...base,
+            selectedProvider: selected.candidate.providerId,
+            resolvedProvider: selected.candidate.providerId,
+            providerStateAtResolution: RESOLVABLE_PROVIDER_STATE,
+            authorization: "allowed",
+            eligibility: "eligible",
+            resolution: "resolved",
+            evidenceId: evidenceId(request.requestId, policy, selected.candidate.providerId)
+        }
+    };
+}
+/** Produces a new immutable evidence record; the resolution snapshot is never rewritten. */
+export function recordPolicyExecution(evidence, result, materialization = "observed") {
+    return { ...evidence, materialization, execution: result, executionResult: result };
+}
+function matchesAttributes(expected, actual) {
+    return Object.entries(expected).every(([key, value]) => actual?.[key] === value);
+}
+function evidenceId(requestId, policy, provider) {
+    return `evd_policy_${requestId}_${policy.policyId}_${policy.policyVersion}_${provider}`.replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+//# sourceMappingURL=resolution-policy.js.map

package/dist/resolution-policy.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appport/sdk",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "AppPort developer SDK: implement a universal application boundary across runtimes and transports.",
   "keywords": [
     "appport",