> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# @parmanasystems/core

> Main SDK package for authority verification

The primary package for producing and verifying authority verification outcomes. Bundles everything you need for production use.

## Install

```bash theme={null}
npm install @parmanasystems/core
```

<Note>
  `@parmanasystems/core` bundles CJS dependencies. Do NOT set `"type": "module"` in `package.json`. Wrap all async code in an `async` function — do not use top-level `await`.
</Note>

## Key exports

| Export               | Description                                                   |
| -------------------- | ------------------------------------------------------------- |
| `executeFromSignals` | Verify authority against a policy                             |
| `confirmExecution`   | Verify a real-world action matches a governance authorization |
| `verifyAttestation`  | Verify an attestation's signature and provenance chain        |
| `LocalSigner`        | Ed25519 signer backed by Node.js crypto                       |
| `LocalVerifier`      | Ed25519 verifier backed by Node.js crypto                     |
| `MemoryReplayStore`  | In-process replay store for development and testing           |
| `RedisReplayStore`   | Redis-backed replay store for production                      |
| `approveOverride`    | Record a human override for a pending decision                |
| `getRuntimeManifest` | Get the current runtime manifest                              |
| `createPolicy`       | Create a new policy definition                                |
| `generateBundle`     | Compile and content-address a policy bundle                   |
| `compilePolicy`      | Validate a policy through all 8 compilation phases            |

### Signal provenance exports

| Export                        | Description                                                        |
| ----------------------------- | ------------------------------------------------------------------ |
| `withProvenance`              | Wrap a signal value with provenance metadata                       |
| `withoutProvenance`           | Wrap a signal value with no provenance (backward-compatible)       |
| `extractSignalValues`         | Strip provenance and extract raw values for policy evaluation      |
| `extractProvenanceMap`        | Extract the provenance layer of a `GovernedSignalMap`              |
| `validateProvenance`          | Check trust levels, required sources, and evidence completeness    |
| `hashEvidence`                | SHA-256 hash of raw evidence before transformation                 |
| `hashProvenance`              | Deterministic hash of a complete `SignalProvenance` record         |
| `hashProvenanceSummary`       | Hash the provenance layer of all governed signals                  |
| `documentProvenance`          | Build provenance for document AI / OCR extraction                  |
| `accountAggregatorProvenance` | Build provenance for Account Aggregator (RBI AA framework) signals |
| `voiceTranscriptProvenance`   | Build provenance for voice transcript signals                      |

### Signal provenance types

| Type                         | Description                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------ |
| `GovernedSignal<T>`          | Signal value + optional provenance metadata                                                |
| `GovernedSignalMap`          | `Record<string, GovernedSignal>` — provenance-aware signal map                             |
| `SignalProvenance`           | Full provenance record for a single signal                                                 |
| `SourceAttestation`          | Cryptographic proof of signal origin from an external system                               |
| `VerificationMethod`         | How the source was verified (`"signature"`, `"tls"`, `"api-key"`, `"manual"`, `"unknown"`) |
| `SourceType`                 | Source classification (`"financial_api"`, `"government_api"`, `"document_ai"`, etc.)       |
| `TrustLevel`                 | Trust classification (`"low"`, `"medium"`, `"high"`)                                       |
| `ProvenanceValidationResult` | Result of `validateProvenance` including trust summary                                     |

## Quick example

```typescript theme={null}
import crypto from "crypto";
import {
  executeFromSignals,
  confirmExecution,
  verifyAttestation,
  LocalSigner,
  LocalVerifier,
  MemoryReplayStore,
} from "@parmanasystems/core";

async function main() {
  const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519", {
    privateKeyEncoding: { type: "pkcs8", format: "pem" },
    publicKeyEncoding:  { type: "spki",  format: "pem" },
  });

  const signer   = new LocalSigner(privateKey);
  const verifier = new LocalVerifier(publicKey);
  const store    = new MemoryReplayStore();

  const attestation = await executeFromSignals(
    {
      policyId:      "loan-approval",
      policyVersion: "1.0.0",
      signals:       { credit_score: 720, loan_amount: 15000 },
    },
    signer,
    verifier,
    undefined, // use default runtime paths
    store
  );

  console.log(attestation.decision);
  // { action: "approve", requires_override: false, reason: "Credit score meets standard threshold." }

  const result = verifyAttestation(attestation, verifier);
  console.log(result.valid); // true

  // Confirm a real-world action against the authorization
  const proof = await confirmExecution(
    {
      attestation,
      executedAction: {
        type:       "LOAN_DISBURSED",
        payload:    { amount: 15000 },
        executedAt: new Date().toISOString(),
      },
    },
    signer,
    verifier,
    store
  );

  console.log(proof.match); // true — action matches authorization
}

main().catch(console.error);
```

## When to use @parmanasystems/core vs individual packages

`@parmanasystems/core` re-exports everything you need for production use. Use it unless you have a specific reason to depend on a lower-level package directly.

| Situation                                       | Recommendation                                                        |
| ----------------------------------------------- | --------------------------------------------------------------------- |
| Building a production application               | Use `@parmanasystems/core`                                            |
| Building a tool that only verifies attestations | Use `@parmanasystems/verifier` directly to minimize dependencies      |
| Building a CI/CD policy compiler                | Use `@parmanasystems/governance` directly                             |
| Embedding governance in a server                | Use `@parmanasystems/server` to get HTTP routes out of the box        |
| Working with signal provenance only             | Use `@parmanasystems/provenance` directly if you don't need execution |
| Implementing a custom runtime                   | Use `@parmanasystems/execution` for the core pipeline                 |

## Use Cases

### NBFC loan origination with signal provenance

A non-banking financial company uses `@parmanasystems/core` to govern loan decisions with Account Aggregator data. One import covers execution, verification, provenance, and replay:

```typescript theme={null}
import {
  executeFromSignals,
  withProvenance,
  accountAggregatorProvenance,
  validateProvenance,
  extractSignalValues,
  LocalSigner,
  LocalVerifier,
  RedisReplayStore,
} from "@parmanasystems/core";

const signals = {
  monthly_income: withProvenance(
    aaResponse.derivedMonthlyIncome,
    accountAggregatorProvenance({
      consentId: aaResponse.consentId,
      fiuId:     "FIU-NBFC-001",
      fetchedAt: aaResponse.fetchedAt,
      rawData:   aaResponse.rawFiData,
    })
  ),
  credit_score: 720,
  employed:     true,
};

const validation = validateProvenance(signals, { minimumTrustLevel: "verified" });
if (!validation.valid) throw new Error(validation.errors.join(", "));

const attestation = await executeFromSignals(
  {
    policyId:      "personal-loan",
    policyVersion: "1.0.0",
    signals:       extractSignalValues(signals),
  },
  signer, verifier, undefined, store
);
```

### UPI fraud decision with error handling

A payment processor evaluates each UPI transaction and handles the common error codes:

```typescript theme={null}
import { executeFromSignals, RedisReplayStore, LocalSigner, LocalVerifier } from "@parmanasystems/core";
import { ErrorCodes } from "@parmanasystems/execution";

try {
  const attestation = await executeFromSignals(
    {
      policyId:      "upi-fraud-gate",
      policyVersion: "1.0.0",
      signals: {
        transaction_amount: 50000,
        risk_score:         87,
        is_foreign:         false,
      },
    },
    signer, verifier, undefined, store
  );
  return attestation.decision.action; // "fraud_review" | "approve"
} catch (err: any) {
  if (err.message?.includes(ErrorCodes.INV_013)) {
    // Already executed — idempotent return
    return cachedDecision;
  }
  throw err;
}
```

### Insurance claim verification by an auditor

An IRDAI auditor verifies a batch of motor insurance attestations. `@parmanasystems/core` ships `verifyAttestation` — no runtime or database access needed:

```typescript theme={null}
import { verifyAttestation, LocalVerifier } from "@parmanasystems/core";

const verifier = new LocalVerifier(insurerPublicKey);

for (const attestation of auditBatch) {
  const result = verifyAttestation(attestation, verifier);
  if (!result.valid) {
    flag(attestation.executionId, result.errors);
  }
}
```

## See also

* [Quickstart](/quickstart) - end-to-end example with policy setup
* [API Reference](/reference/api-reference) - full function signatures and types
* [Production Checklist](/guides/production-checklist) - before going live