# @lssm-tech/integration.lssm-os-cache-redis

Qualified Redis and Valkey cache, coordination, and SQL-authoritative stream acceleration for LSSM OS.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `2.0.4`
- Package path: `packages/integrations/lssm-os-cache-redis`
- Manifest path: `packages/integrations/lssm-os-cache-redis/package.json`
- Manifest Git blob: `f5c6954fe479bfaa2e114dd89914832fb9125f76`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/integration.lssm-os-cache-redis](https://lssm.co/docs/packages/integration.lssm-os-cache-redis/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/integration.lssm-os-cache-redis.txt)

## Package metadata

```json
{
  "layer": "integrations",
  "physicalArea": null,
  "primaryArea": "delivery-and-infrastructure",
  "classification": {
    "privateDeclared": null,
    "catalogFamily": "integrations",
    "catalogKind": "integration",
    "catalogStatus": "active",
    "adoptionMode": "adoptable",
    "stability": "experimental"
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: not declared; publication is not verified.

Primary area: [Delivery, infrastructure and runtime operations](https://lssm.co/docs/areas/delivery-and-infrastructure/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/integrations/lssm-os-cache-redis/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/README.md",
  "blobSha": "a2b5af1c5eda1e04780a95c8d8023557b401588d",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "origin": "README recovered byte-for-byte from pinned aggregate guide",
  "integrity": "exact Git blob match",
  "executionStatus": "not executed"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# `@lssm-tech/integration.lssm-os-cache-redis`

Optional Redis and Valkey acceleration for LSSM OS T2 topologies. The package
implements the provider-neutral Runtime Node distributed-cache, coordination,
and event-stream ports through a small injected command client. It does not
load SDK modules, read credentials, or own connection lifecycle.

SQL remains authoritative. A cache miss, eviction, adapter timeout, or disabled
deployment must fall back to the T1 database path. Cache entries are bound to
the full tenant/workspace/environment/product/application scope, topology
generation, and qualified capability digest. Values are bounded, digest
verified, UTF-8 only, and rejected when they contain credential material.

Invalidation uses one Redis/Valkey Lua transition to delete the entry and append
the exact signed invalidation to a monotonic per-namespace reconciliation log.
Coordination uses compare-and-set Lua transitions, bounded TTLs, and monotonic
fences. These coordination fences are deliberately distinct from Runtime Node
work-order fences and never authorize an external effect.

Redis Streams is available as an optional wake-up accelerator over a qualified
SQL `DurableQueuePortV2`. Admission, claim, queue fences, reconciliation, and
acknowledgement remain SQL-authoritative. Stream entries contain only immutable
envelope/outbox identifiers and digests; they never contain payloads, secrets,
claims, effect fences, or provider results. Redis failure or loss therefore
degrades to bounded SQL polling without changing execution correctness. The
adapter validates an independent `redis_streams` capability/version binding and
distinct component profile, and will not substitute that transport binding for
the SQL authority binding.

Compose an official `redis` client with `fromRedisClientV1`, or `ioredis` with
`fromIoRedisClientV1`. The same command surface works with Valkey-compatible
clients. Production readiness requires an exact, digest-valid
`CacheCapabilityProfileV1` whose engine is `redis` or `valkey`, plus deployment
qualification for the configured server/client/topology versions. The package
contains deterministic conformance tests but does not claim a live managed
Redis or Valkey service qualification.

Wake consumers recover idle pending entries with `XAUTOCLAIM` before reading
new entries. `minimumPendingIdleMilliseconds` defaults to 30 seconds and is
bounded between one second and one day. Approximate stream trimming is also
reconciled with the deduplication map: a mapping is reused only while its exact
stream entry still exists, so a trimmed hint can be republished from the SQL
outbox instead of becoming permanently unreachable.

Run `bun run qualify:local` after pulling `redis:8.2.1-alpine` to execute the
real standalone Redis qualification. The command refuses to pull implicitly,
binds both the local image ID and repository digest, disables container
networking and TCP, uses a private Unix socket, stores AOF state in a uniquely
created host temp directory, and removes the container and directory on every
exit path. It verifies cache put/get, atomic invalidation ordering, stale-write
rejection, poisoned-value containment, 100-way coordination contention,
fencing, AOF restart persistence, Streams deduplication, pending recovery,
acknowledgement, trim-map repair, and SQL-authoritative behavior while Redis is
stopped.

Run `bun run qualify:valkey-local` after pulling
`valkey/valkey:9.1.1-alpine` for the same matrix against a distinct Valkey
engine profile, official image and repository digest, `valkey-server`,
`valkey-cli`, and private Valkey socket. Redis success is never reused as
Valkey evidence.

These commands provide local-live standalone Redis and Valkey evidence only.
They do not qualify Sentinel, Cluster, managed primary/replica failover,
resharding, TLS, ACLs, regional placement, sustained scale, or production
operations; those rows remain release blockers.


## Declared capabilities

### Redis and Valkey runtime acceleration

Capability ID: `lssm-os.cache.redis`

Add qualified cache, coordination, invalidation, and stream wake-up acceleration while keeping SQL authoritative for LSSM OS execution.

Use cases:

- Accelerate scoped runtime reads with digest-verified Redis or Valkey cache entries
- Use Redis Streams as a lossy wake-up layer over a SQL-authoritative durable queue

Constraints:

```json
{
  "platforms": [
    "server"
  ],
  "runtimes": [
    "bun",
    "node"
  ],
  "avoidWhen": [
    "Redis or Valkey would become the durable source of truth for work admission, effects, or acknowledgements.",
    "The deployment lacks an exact qualified cache or stream capability profile."
  ],
  "requires": [
    "Redis or Valkey",
    "SQL-authoritative LSSM OS runtime"
  ]
}
```

Other capability declarations:

```json
{
  "status": "active",
  "aliases": [
    "Redis",
    "Valkey",
    "distributed cache",
    "Redis Streams"
  ],
  "pythonEquivalents": [
    "redis-py"
  ],
  "alternatives": [],
  "relationships": [],
  "resolutionPriority": 70
}
```

Capability imports:

```json
[
  {
    "from": "@lssm-tech/integration.lssm-os-cache-redis",
    "symbols": []
  }
]
```

## Catalogue metadata

```json
{
  "family": "integrations",
  "kind": "integration",
  "status": "active",
  "adoptionMode": "adoptable",
  "stability": "experimental",
  "platforms": [
    "server"
  ],
  "runtimes": [
    "bun",
    "node"
  ],
  "entrypoints": [
    "."
  ],
  "examples": [],
  "replacements": []
}
```

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[
  {
    "capabilityId": "lssm-os.cache.redis",
    "from": "@lssm-tech/integration.lssm-os-cache-redis",
    "symbols": []
  }
]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

- `@lssm-tech/integration.lssm-os-cache-redis` — subpath `.`
  - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/index.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/adapter-helpers` — subpath `./adapter-helpers`
  - `unconditional`: `./src/adapter-helpers.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/adapter-helpers.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/cache` — subpath `./cache`
  - `unconditional`: `./src/cache.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/cache.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/client` — subpath `./client`
  - `unconditional`: `./src/client.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/client.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/coordination` — subpath `./coordination`
  - `unconditional`: `./src/coordination.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/coordination.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/keys` — subpath `./keys`
  - `unconditional`: `./src/keys.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/keys.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/results` — subpath `./results`
  - `unconditional`: `./src/results.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/results.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/scripts` — subpath `./scripts`
  - `unconditional`: `./src/scripts.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/scripts.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/stream-scripts` — subpath `./stream-scripts`
  - `unconditional`: `./src/stream-scripts.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/stream-scripts.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/stream-validation` — subpath `./stream-validation`
  - `unconditional`: `./src/stream-validation.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/stream-validation.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/streams` — subpath `./streams`
  - `unconditional`: `./src/streams.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/streams.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/types` — subpath `./types`
  - `unconditional`: `./src/types.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/types.ts); verified source file.

- `@lssm-tech/integration.lssm-os-cache-redis/validation` — subpath `./validation`
  - `unconditional`: `./src/validation.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-cache-redis/src/validation.ts); verified source file.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": "./dist/index.d.ts",
  "files": [
    "dist",
    "!dist/**/*test*",
    "README.md"
  ],
  "publishExports": {
    ".": {
      "types": "./dist/index.d.ts",
      "browser": "./dist/browser/index.js",
      "bun": "./dist/index.js",
      "node": "./dist/node/index.js",
      "default": "./dist/index.js"
    },
    "./adapter-helpers": {
      "types": "./dist/adapter-helpers.d.ts",
      "browser": "./dist/browser/adapter-helpers.js",
      "bun": "./dist/adapter-helpers.js",
      "node": "./dist/node/adapter-helpers.js",
      "default": "./dist/adapter-helpers.js"
    },
    "./cache": {
      "types": "./dist/cache.d.ts",
      "browser": "./dist/browser/cache.js",
      "bun": "./dist/cache.js",
      "node": "./dist/node/cache.js",
      "default": "./dist/cache.js"
    },
    "./client": {
      "types": "./dist/client.d.ts",
      "browser": "./dist/browser/client.js",
      "bun": "./dist/client.js",
      "node": "./dist/node/client.js",
      "default": "./dist/client.js"
    },
    "./coordination": {
      "types": "./dist/coordination.d.ts",
      "browser": "./dist/browser/coordination.js",
      "bun": "./dist/coordination.js",
      "node": "./dist/node/coordination.js",
      "default": "./dist/coordination.js"
    },
    "./keys": {
      "types": "./dist/keys.d.ts",
      "browser": "./dist/browser/keys.js",
      "bun": "./dist/keys.js",
      "node": "./dist/node/keys.js",
      "default": "./dist/keys.js"
    },
    "./results": {
      "types": "./dist/results.d.ts",
      "browser": "./dist/browser/results.js",
      "bun": "./dist/results.js",
      "node": "./dist/node/results.js",
      "default": "./dist/results.js"
    },
    "./scripts": {
      "types": "./dist/scripts.d.ts",
      "browser": "./dist/browser/scripts.js",
      "bun": "./dist/scripts.js",
      "node": "./dist/node/scripts.js",
      "default": "./dist/scripts.js"
    },
    "./stream-scripts": {
      "types": "./dist/stream-scripts.d.ts",
      "browser": "./dist/browser/stream-scripts.js",
      "bun": "./dist/stream-scripts.js",
      "node": "./dist/node/stream-scripts.js",
      "default": "./dist/stream-scripts.js"
    },
    "./stream-validation": {
      "types": "./dist/stream-validation.d.ts",
      "browser": "./dist/browser/stream-validation.js",
      "bun": "./dist/stream-validation.js",
      "node": "./dist/node/stream-validation.js",
      "default": "./dist/stream-validation.js"
    },
    "./streams": {
      "types": "./dist/streams.d.ts",
      "browser": "./dist/browser/streams.js",
      "bun": "./dist/streams.js",
      "node": "./dist/node/streams.js",
      "default": "./dist/streams.js"
    },
    "./types": {
      "types": "./dist/types.d.ts",
      "browser": "./dist/browser/types.js",
      "bun": "./dist/types.js",
      "node": "./dist/node/types.js",
      "default": "./dist/types.js"
    },
    "./validation": {
      "types": "./dist/validation.d.ts",
      "browser": "./dist/browser/validation.js",
      "bun": "./dist/validation.js",
      "node": "./dist/node/validation.js",
      "default": "./dist/validation.js"
    }
  }
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/lib.crypto-utils](https://lssm.co/docs/packages/lib.crypto-utils/): `^2.0.1`
- [@lssm-tech/lib.lssm-os-runtime](https://lssm.co/docs/packages/lib.lssm-os-runtime/): `^2.1.1`
- [@lssm-tech/lib.lssm-os-spec](https://lssm.co/docs/packages/lib.lssm-os-spec/): `^2.0.1`
- [@lssm-tech/lib.orchestration-spec](https://lssm.co/docs/packages/lib.orchestration-spec/): `workspace:^`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- [@lssm-tech/tool.bun](https://lssm.co/docs/packages/tool.bun/): `workspace:*`
- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `@types/bun`: `catalog:types`
- `typescript`: `^7.0.2`

### Peer dependency metadata

```json
{}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "build": "contractspec-bun-build build",
  "build:bundle": "contractspec-bun-build transpile",
  "build:types": "contractspec-bun-build types",
  "lint:check": "node ../../../scripts/biome.cjs check .",
  "pack:verify": "bun run build && bun scripts/verify-pack.ts",
  "qualify:local": "bun scripts/qualify-redis-local.ts",
  "qualify:valkey-local": "bun scripts/qualify-valkey-local.ts",
  "test": "bun test",
  "typecheck": "tsgo --noEmit",
  "typecheck:qualification": "tsgo --noEmit -p tsconfig.qualification.json"
}
```

## Declared documentation links

- [LSSM OS Redis and Valkey acceleration](https://www.npmjs.com/package/%40lssm-tech%2Fintegration.lssm-os-cache-redis) — declared link; destination not verified.

```json
{
  "url": "https://www.npmjs.com/package/%40lssm-tech%2Fintegration.lssm-os-cache-redis",
  "kind": "readme"
}
```

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/integration.lssm-os-cache-redis.txt",
  "route": "/llms/integration.lssm-os-cache-redis",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/integration.lssm-os-cache-redis.txt",
  "blobSha": "a2b5af1c5eda1e04780a95c8d8023557b401588d",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```