@harapter/core 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Harapter contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,111 @@
+# `@harapter/core`
+
+`@harapter/core` is the provider-agnostic TypeScript API for Harapter. It owns
+portable contracts and the runtime checks that can be applied without knowing a
+Provider identity.
+
+## Installation
+
+```bash
+pnpm add @harapter/core@next
+```
+
+## Public entrypoints
+
+- `HarnessRegistry` dynamically registers Adapter factories and connects host
+  Profiles.
+- `HarnessClient`, `HarnessSession`, and `HarnessRun` define the portable
+  lifecycle.
+- `HarnessEvent` and `RunResult` define ordered events and one terminal result.
+- `CapabilityManifest` distinguishes `native`, `emulated`, `adapter_controlled`,
+  `unsupported`, and `unknown`; a missing key means the active Adapter does not
+  recognize that capability name.
+- `HarnessError` carries a stable category and an explicit retry decision.
+- `ExtensionRegistry` provides typed, Provider-bound extension lookup.
+- `native()` exposes an explicit Provider-bound escape hatch.
+- `assertSessionOwnership()` rejects a Session reference whose Provider or
+  Profile differs from the active Client before resume traffic is sent.
+- `assertSessionCompatibility()` rejects a Session reference whose runtime or
+  protocol fingerprint differs from the active Client.
+
+`HarnessRegistry.connect()` checks the registered connection kind, Client
+descriptor identity, and Capability Manifest identity on every connection, then
+checks any requested capability modes. `CapabilityRequirement.acceptedModes`
+defaults to `native`; a host must opt in to weaker modes explicitly. Registry
+validation uses an isolated Profile snapshot so an Adapter cannot rewrite the
+requested identity or requirements. Once a Client exists, descriptor or
+capability probe failures close it before a safe portable error is returned.
+
+## Lifecycle
+
+A `SessionRef` remains bound to the Provider and Profile that created it. Core
+does not inspect `providerState`, parse Provider-native identifiers, migrate
+checkpoints, or infer resume support.
+
+A Run event sequence is monotonic and ends in exactly one of `run.completed`,
+`run.cancelled`, `run.failed`, or `connection.aborted`. A connection or process
+abort is not native Run cancellation. Native, emulated, and Adapter-controlled
+cancellation return distinct results. Adapters own event production and
+terminal-result mapping; the shared conformance package checks these obligations
+through the public interfaces.
+
+`close()` is asynchronous and must be idempotent. A Client rejected during
+Registry validation is closed before the validation error is returned. Cleanup
+failure is reported as `connection_failed` without attaching an unredacted
+cause.
+
+## Errors and sensitive data
+
+Every `HarnessError` requires callers to state `retryable`; Core does not infer
+retry behavior from a Provider name or error message. Provider causes and
+details must be redacted before an Adapter attaches them. Hosts should not log
+`cause`, `providerState`, raw events, or Provider results by default.
+
+Profiles carry Secret references, not credential values. Credential resolution,
+runtime installation, authentication, process policy, and product persistence
+remain host or Provider responsibilities.
+
+## Example
+
+The deterministic Fake Provider gives the Core flow executable evidence without
+introducing a Provider dependency:
+
+```ts
+import { HarnessRegistry } from '@harapter/core';
+import {
+  createFakeProfile,
+  createFakeProviderFactory,
+} from '@harapter/conformance';
+
+const registry = new HarnessRegistry();
+registry.register(createFakeProviderFactory());
+
+const client = await registry.connect(createFakeProfile());
+const session = await client.createSession();
+const run = await session.start({
+  parts: [{ type: 'text', text: 'synthetic input' }],
+});
+
+for await (const event of run.events()) {
+  console.log(event.type);
+}
+
+const result = await run.result();
+await session.close();
+await client.close();
+```
+
+## Limitations
+
+- No Provider Adapter, transport, canonical wire schema, persistence layer, or
+  runtime installer is included.
+- Core defines event ordering and terminality but does not buffer, redact, or
+  reinterpret Provider streams. Each Adapter and transport must prove bounded
+  buffering, redaction, and terminal mapping.
+- Interaction, artifact, usage, resume, cancellation, and other optional
+  behavior depend on the active Capability Manifest.
+- The public API remains pre-alpha. Published packages use the opt-in `next`
+  dist-tag and may contain breaking changes before 1.0.
+
+The complete target contract remains in the
+[API design](../../docs/design/api-design.md).

package/dist/contracts.d.ts

@@ -0,0 +1,258 @@
+import type { ProfileId, ProviderId, ProviderSessionId, RunId } from './identifiers.js';
+/** Supported connection ownership and transport families. */
+export type ConnectionKind = 'sdk' | 'process' | 'endpoint' | 'local_socket';
+/** Reference resolved by a host-controlled secret store. */
+export interface SecretRef {
+    readonly scheme: string;
+    readonly id: string;
+}
+/** Provider connection selected by a host Profile. */
+export type ProviderConnection = {
+    kind: 'sdk';
+    client?: unknown;
+    factory?: unknown;
+    ownership: 'host' | 'adapter';
+} | {
+    kind: 'process';
+    command: string;
+    args?: readonly string[];
+    cwd?: string;
+    envRefs?: Readonly<Record<string, SecretRef>>;
+    ownership: 'host' | 'adapter' | 'external';
+} | {
+    kind: 'endpoint';
+    url: string;
+    transport?: 'http' | 'sse' | 'websocket' | 'acp';
+    authRef?: SecretRef;
+    ownership: 'host' | 'external';
+} | {
+    kind: 'local_socket';
+    path: string;
+    transport: 'http' | 'jsonrpc' | 'acp';
+    authRef?: SecretRef;
+    ownership: 'host' | 'external';
+};
+/** Host-owned selectable configuration for one Provider connection. */
+export interface HarnessProfile {
+    readonly profileId: ProfileId;
+    readonly displayName: string;
+    readonly providerId: ProviderId;
+    readonly connection: ProviderConnection;
+    readonly providerOptions?: Readonly<Record<string, unknown>>;
+    readonly requiredCapabilities?: readonly CapabilityRequirement[];
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+/** Static Adapter metadata used for dynamic discovery. */
+export interface ProviderDescriptor {
+    providerId: ProviderId;
+    displayName: string;
+    connectionKinds: readonly ConnectionKind[];
+    documentationUrl?: string;
+}
+/** Factory implemented by one independently versioned Provider package. */
+export interface ProviderAdapterFactory {
+    descriptor(): ProviderDescriptor;
+    connect(profile: HarnessProfile): Promise<HarnessClient>;
+}
+/** Runtime description of an active Profile connection. */
+export interface ClientDescriptor {
+    providerId: ProviderId;
+    profileId: ProfileId;
+    displayName: string;
+    connectionKind: ConnectionKind;
+    runtime?: {
+        name?: string;
+        version?: string;
+        protocol?: string;
+        protocolVersion?: string;
+    };
+    compatibility: 'supported' | 'experimental' | 'unsupported';
+    warnings?: readonly CompatibilityWarning[];
+}
+/** Non-sensitive compatibility diagnostic. */
+export interface CompatibilityWarning {
+    code: string;
+    message: string;
+}
+/** Capability implementation strength observed for the active connection. */
+export type CapabilityMode = 'native' | 'emulated' | 'adapter_controlled' | 'unsupported' | 'unknown';
+/** Runtime evidence for one portable or Provider-namespaced capability. */
+export interface CapabilityStatus {
+    mode: CapabilityMode;
+    reason?: string;
+    limits?: Readonly<Record<string, number | string | boolean>>;
+    source?: 'handshake' | 'schema' | 'version_profile' | 'configuration';
+}
+/** Capability observations for one active Profile connection. */
+export interface CapabilityManifest {
+    providerId: ProviderId;
+    profileId: ProfileId;
+    capabilities: Readonly<Record<string, CapabilityStatus>>;
+    observedAt: string;
+    runtimeIdentity?: string;
+}
+/** Host requirement checked before a Registry returns a connected Client. */
+export interface CapabilityRequirement {
+    readonly name: string;
+    readonly acceptedModes?: readonly CapabilityMode[];
+}
+/** Options for refreshing or reusing capability observations. */
+export interface CapabilityProbeOptions {
+    refresh?: boolean;
+}
+/** Portable Client bound to one Provider and Profile. */
+export interface HarnessClient {
+    descriptor(): Promise<ClientDescriptor>;
+    capabilities(options?: CapabilityProbeOptions): Promise<CapabilityManifest>;
+    createSession(input?: CreateSessionInput): Promise<HarnessSession>;
+    resumeSession(ref: SessionRef): Promise<HarnessSession>;
+    extensions(): ProviderExtensionRegistry;
+    native<T = unknown>(guard?: (value: unknown) => value is T): T | undefined;
+    close(): Promise<void>;
+}
+/** Optional settings applied while creating a Provider session. */
+export interface CreateSessionInput {
+    workspace?: WorkspaceRef;
+    systemContext?: string;
+    model?: ModelSelection;
+    providerOptions?: Readonly<Record<string, unknown>>;
+    metadata?: Readonly<Record<string, string>>;
+}
+/** Portable Session bound to the Client that created it. */
+export interface HarnessSession {
+    ref(): SessionRef;
+    capabilities(): Promise<CapabilityManifest>;
+    start(input: HarnessInput, options?: RunOptions): Promise<HarnessRun>;
+    respond(requestId: string, response: InteractionResponse): Promise<void>;
+    close(): Promise<void>;
+}
+/** Persistable opaque reference that only its owning Adapter may interpret. */
+export interface SessionRef {
+    providerId: ProviderId;
+    profileId: ProfileId;
+    providerSessionId: ProviderSessionId;
+    compatibilityRef?: string;
+    providerState?: unknown;
+}
+/** One active execution on a Session. */
+export interface HarnessRun {
+    ref(): RunRef;
+    events(): AsyncIterable<HarnessEvent>;
+    cancel(): Promise<CancelResult>;
+    result(): Promise<RunResult>;
+}
+/** Stable reference for one Client-scoped Run. */
+export interface RunRef {
+    providerId: ProviderId;
+    profileId: ProfileId;
+    sessionId: ProviderSessionId;
+    runId: RunId;
+    providerRunId?: string;
+}
+/** Portable run controls and Provider-local options. */
+export interface RunOptions {
+    timeoutMs?: number;
+    providerOptions?: Readonly<Record<string, unknown>>;
+    metadata?: Readonly<Record<string, string>>;
+}
+/** Observable result of a cancellation request. */
+export interface CancelResult {
+    mode: 'native' | 'emulated' | 'connection_aborted' | 'already_terminal';
+}
+/** Portable user input. */
+export interface HarnessInput {
+    parts: readonly InputPart[];
+    metadata?: Readonly<Record<string, string>>;
+}
+/** One Provider-independent or explicit Provider-native input part. */
+export type InputPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'file_ref';
+    uri: string;
+    mediaType?: string;
+} | {
+    type: 'image_ref';
+    uri: string;
+    mediaType?: string;
+} | {
+    type: 'provider';
+    name: string;
+    value: unknown;
+};
+/** URI reference to the workspace a Provider may use. */
+export interface WorkspaceRef {
+    uri: string;
+}
+/** Provider-owned model identifier plus Provider-local selection options. */
+export interface ModelSelection {
+    id: string;
+    providerOptions?: Readonly<Record<string, unknown>>;
+}
+/** Stable portable event vocabulary. */
+export type HarnessEventType = 'run.started' | 'message.delta' | 'message.completed' | 'reasoning.delta' | 'reasoning.completed' | 'tool.started' | 'tool.updated' | 'tool.completed' | 'interaction.requested' | 'interaction.resolved' | 'artifact.created' | 'usage.updated' | 'run.completed' | 'run.cancelled' | 'run.failed' | 'connection.aborted' | 'provider';
+/** One ordered event emitted by a Run. */
+export interface HarnessEvent<T = unknown> {
+    id: string;
+    type: HarnessEventType;
+    providerId: ProviderId;
+    profileId: ProfileId;
+    sessionId: ProviderSessionId;
+    runId: RunId;
+    sequence: number;
+    timestamp: string;
+    data: T;
+    providerEventType?: string;
+    raw?: unknown;
+}
+/** Portable interaction requested by a Provider. */
+export interface InteractionRequest {
+    requestId: string;
+    kind: 'approval' | 'user_input' | 'provider';
+    title?: string;
+    prompt?: string;
+    schema?: unknown;
+    providerState?: unknown;
+}
+/** Host response to a pending interaction. */
+export type InteractionResponse = {
+    kind: 'approval';
+    decision: 'approve' | 'deny';
+    providerOptions?: unknown;
+} | {
+    kind: 'user_input';
+    parts: readonly InputPart[];
+} | {
+    kind: 'provider';
+    value: unknown;
+};
+/** Token accounting when the Provider exposes it. */
+export interface UsageSummary {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+/** Exactly one terminal outcome for a Run. */
+export interface RunResult {
+    status: 'completed' | 'cancelled' | 'failed' | 'connection_aborted';
+    finalMessage?: string;
+    usage?: UsageSummary;
+    providerResult?: unknown;
+}
+/** Read-only Provider extension lookup. */
+export interface ProviderExtensionRegistry {
+    list(): readonly ProviderExtensionDescriptor[];
+    has(name: string): boolean;
+    get<T>(name: string, guard?: (value: unknown) => value is T): T | undefined;
+}
+/** Discoverable metadata for one typed Provider extension. */
+export interface ProviderExtensionDescriptor {
+    name: string;
+    providerId: ProviderId;
+    displayName: string;
+    description?: string;
+    documentationUrl?: string;
+    stability?: 'stable' | 'experimental';
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

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

package/dist/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":""}

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+import type { ProfileId, ProviderId } from './identifiers.js';
+/** Stable portable error categories. */
+export type HarnessErrorCode = 'provider_not_found' | 'profile_invalid' | 'runtime_not_found' | 'connection_failed' | 'authentication_failed' | 'provider_api_incompatible' | 'unsupported_capability' | 'invalid_request' | 'session_not_found' | 'session_provider_mismatch' | 'run_conflict' | 'timeout' | 'provider_error' | 'connection_aborted';
+/** Explicit diagnostics supplied when constructing a portable error. */
+export interface HarnessErrorOptions {
+    retryable: boolean;
+    providerId?: ProviderId;
+    profileId?: ProfileId;
+    providerCode?: string;
+    details?: Readonly<Record<string, unknown>>;
+    cause?: unknown;
+}
+/**
+ * Portable failure with an explicit stable category and retry decision.
+ * Provider causes must be redacted before they are attached.
+ */
+export declare class HarnessError extends Error {
+    readonly code: HarnessErrorCode;
+    readonly retryable: boolean;
+    readonly providerId: ProviderId | undefined;
+    readonly profileId: ProfileId | undefined;
+    readonly providerCode: string | undefined;
+    readonly details: Readonly<Record<string, unknown>> | undefined;
+    /**
+     * @param code - Stable portable category.
+     * @param message - Safe human-readable summary.
+     * @param options - Explicit retry and redacted Provider diagnostics.
+     */
+    constructor(code: HarnessErrorCode, message: string, options: HarnessErrorOptions);
+}
+/**
+ * Narrow an unknown failure to {@link HarnessError}.
+ * @param error - Unknown thrown value.
+ * @returns Whether the value is a portable Harapter error.
+ */
+export declare function isHarnessError(error: unknown): error is HarnessError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9D,wCAAwC;AACxC,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,GACnB,uBAAuB,GACvB,2BAA2B,GAC3B,wBAAwB,GACxB,iBAAiB,GACjB,mBAAmB,GACnB,2BAA2B,GAC3B,cAAc,GACd,SAAS,GACT,gBAAgB,GAChB,oBAAoB,CAAC;AAEzB,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAEhE;;;;OAIG;gBAED,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB;CAW/B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE"}

package/dist/errors.js

@@ -0,0 +1,36 @@
+/**
+ * Portable failure with an explicit stable category and retry decision.
+ * Provider causes must be redacted before they are attached.
+ */
+export class HarnessError extends Error {
+    code;
+    retryable;
+    providerId;
+    profileId;
+    providerCode;
+    details;
+    /**
+     * @param code - Stable portable category.
+     * @param message - Safe human-readable summary.
+     * @param options - Explicit retry and redacted Provider diagnostics.
+     */
+    constructor(code, message, options) {
+        super(message, { cause: options.cause });
+        this.name = 'HarnessError';
+        this.code = code;
+        this.retryable = options.retryable;
+        this.providerId = options.providerId;
+        this.profileId = options.profileId;
+        this.providerCode = options.providerCode;
+        this.details = options.details;
+    }
+}
+/**
+ * Narrow an unknown failure to {@link HarnessError}.
+ * @param error - Unknown thrown value.
+ * @returns Whether the value is a portable Harapter error.
+ */
+export function isHarnessError(error) {
+    return error instanceof HarnessError;
+}
+//# sourceMappingURL=errors.js.map