feat(cedar-hitl): TaskApprovalsTable + SlackUserMapping + status enum

Lands the stateless CDK primitives for Cedar-HITL approval gates so
Chunk 5's REST handlers can be wired onto concrete tables. Completes
§15.2 tasks 9, 20, and 25.

Constructs
----------

``TaskApprovalsTable`` (§10.1)
  - PK ``task_id`` + SK ``request_id`` (ULID). Matches the agent-side
    primitives landed in the prior commit.
  - GSI ``user_id-status-index`` with user_id PK + status SK and an
    ``INCLUDE`` projection limited to the fields GET /v1/pending
    renders. Three deny-sensitive attrs (``deny_reason``, ``scope``,
    ``tool_input_sha256``) deliberately omitted from the projection —
    the list endpoint only returns PENDING rows in practice, but
    excluding them kills the projection-leak concern outright and
    costs no bytes today.
  - Exports ``USER_STATUS_INDEX_NAME`` as a module constant + mirrors
    it on ``construct.userStatusIndexName`` so handlers referencing
    the GSI fail compile-time on a rename.
  - TTL attribute ``ttl`` (agent writes ``created_at + timeout_s +
    120s``).
  - No DynamoDB streams per §11.2. TaskEventsTable carries the audit
    fan-out; streams here would duplicate.
  - Default RemovalPolicy.DESTROY to match the rest of the sample.
    Production deploys override to RETAIN per §10.1.

``SlackUserMappingTable`` (§11.2, finding aws-samples#4)
  - Single-key (``slack_user_id`` PK). No SK, no TTL, no GSI, no
    stream. The forward-only shape is the trust boundary — a reverse
    GSI (Cognito → Slack) would let a compromised Cognito sub
    enumerate Slack identities without adding v1 capability.
  - Writes land through LinkSlackUserFn (Chunk 5) which enforces the
    ``attribute_not_exists(slack_user_id)`` condition so a prior
    legitimate mapping cannot be overwritten by a later compromise.

``task-status.ts`` — AWAITING_APPROVAL (§10.3)
  - Added to TaskStatus enum + ACTIVE_STATUSES (NOT TERMINAL_STATUSES:
    the task is alive, paused on a human decision).
  - VALID_TRANSITIONS wires the five edges §10.3 enumerates:
      RUNNING      → AWAITING_APPROVAL  (soft-deny entry)
      HYDRATING    → AWAITING_APPROVAL  (rare early-gate case)
      AWAITING_APPROVAL → RUNNING       (approve / deny resume)
      AWAITING_APPROVAL → CANCELLED     (user cancel mid-approval)
      AWAITING_APPROVAL → FAILED        (stranded-approval reconciler)
  - Notably NOT added:
      AWAITING_APPROVAL → FINALIZING    (approve-during-cleanup race)
      AWAITING_APPROVAL → COMPLETED     (skip RUNNING)
      AWAITING_APPROVAL → TIMED_OUT     (timer lives on the approval
                                         row, not the task clock)
    These are regression tests so a future refactor cannot quietly
    add them and bypass the `awaiting_approval_request_id = :rid`
    invariant.

Tests: +29 total.
  - TaskApprovalsTable (11 tests): PK/SK schema, PAY_PER_REQUEST,
    PITR default + override, TTL attribute, NO streams, GSI schema +
    projection + sensitive-attr exclusion, removal policy default +
    override, ``USER_STATUS_INDEX_NAME`` constant parity with the
    construct field.
  - SlackUserMappingTable (8 tests): single-key schema (explicit
    KeySchema length assertion), PAY_PER_REQUEST, PITR, no streams,
    no reverse GSI, DESTROY default, TTL absent.
  - TaskStatus (+10 tests over existing: 5 new assertions on the
    9-state cardinality, AWAITING_APPROVAL membership, and the
    transition graph including the three forbidden edges). The
    existing assertions updated for the new state count.

No stack wiring yet — ``agent.ts`` instantiation + env var plumbing +
grants land in the next commit alongside the Cedar-WASM Lambda layer.

Author: scoropeza

cdk/src/constructs/slack-user-mapping-table.ts

@@ -0,0 +1,94 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+import { RemovalPolicy } from 'aws-cdk-lib';
+import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+import { Construct } from 'constructs';
+
+/**
+ * Properties for SlackUserMappingTable construct.
+ */
+export interface SlackUserMappingTableProps {
+  /**
+   * Optional table name override.
+   * @default - auto-generated by CloudFormation
+   */
+  readonly tableName?: string;
+
+  /**
+   * Removal policy for the table.
+   * @default RemovalPolicy.DESTROY
+   */
+  readonly removalPolicy?: RemovalPolicy;
+
+  /**
+   * Whether to enable point-in-time recovery.
+   * @default true
+   */
+  readonly pointInTimeRecovery?: boolean;
+}
+
+/**
+ * DynamoDB table mapping Slack user IDs to Cognito subs for
+ * Slack-button approvals (design §11.2, finding #4).
+ *
+ * Schema: `slack_user_id` (PK). One row per Slack identity; the sole
+ * non-key attribute is `cognito_sub`. No GSI is provided for the
+ * reverse direction (Cognito → Slack) because that lookup is not
+ * trust-sensitive and can be derived offline if ever needed.
+ *
+ * Writes are gated through the `LinkSlackUserFn` Lambda (Chunk 5)
+ * which requires BOTH a valid Cognito ID token AND a Slack OAuth
+ * token for the user being mapped. Admins do not have a bulk-write
+ * API, and the `ConditionExpression: attribute_not_exists(slack_user_id)`
+ * on that Put prevents a subsequent Slack-admin compromise from
+ * overwriting an existing mapping.
+ *
+ * NOT provided as part of this construct:
+ *
+ * - Stream (no consumer needs row-change events; every write is a
+ *   user-initiated link, audit lives on CloudTrail + the handler's
+ *   explicit audit event on TaskEventsTable).
+ * - Reverse GSI (Cognito → Slack) — would widen the trust surface
+ *   without adding capability we need in v1.
+ */
+export class SlackUserMappingTable extends Construct {
+  /**
+   * The underlying DynamoDB table. Use this to grant access or read
+   * the table name.
+   */
+  public readonly table: dynamodb.Table;
+
+  constructor(scope: Construct, id: string, props: SlackUserMappingTableProps = {}) {
+    super(scope, id);
+
+    this.table = new dynamodb.Table(this, 'Table', {
+      tableName: props.tableName,
+      partitionKey: {
+        name: 'slack_user_id',
+        type: dynamodb.AttributeType.STRING,
+      },
+      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
+      pointInTimeRecoverySpecification: {
+        pointInTimeRecoveryEnabled: props.pointInTimeRecovery ?? true,
+      },
+      removalPolicy: props.removalPolicy ?? RemovalPolicy.DESTROY,
+    });
+  }
+}

cdk/src/constructs/task-approvals-table.ts

@@ -0,0 +1,146 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+import { RemovalPolicy } from 'aws-cdk-lib';
+import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+import { Construct } from 'constructs';
+
+/**
+ * GSI name for the `user_id-status-index`. Exported so handlers that
+ * issue Query calls against the GSI reference the same identifier the
+ * table was built with — renaming the GSI would break `bgagent pending`
+ * without a loud failure.
+ */
+export const USER_STATUS_INDEX_NAME = 'user_id-status-index';
+
+/**
+ * Properties for TaskApprovalsTable construct.
+ */
+export interface TaskApprovalsTableProps {
+  /**
+   * Optional table name override.
+   * @default - auto-generated by CloudFormation
+   */
+  readonly tableName?: string;
+
+  /**
+   * Removal policy for the table. The design (§10.1) recommends RETAIN
+   * in production to preserve the audit trail; we default to DESTROY to
+   * match the rest of the sample and keep teardowns cheap. Override per
+   * environment.
+   * @default RemovalPolicy.DESTROY
+   */
+  readonly removalPolicy?: RemovalPolicy;
+
+  /**
+   * Whether to enable point-in-time recovery.
+   * @default true
+   */
+  readonly pointInTimeRecovery?: boolean;
+}
+
+/**
+ * DynamoDB table for Cedar-HITL approval gates (design §10.1).
+ *
+ * Schema: `task_id` (PK, ULID matching TaskTable) + `request_id` (SK,
+ * ULID minted by the agent). Each row represents one human-in-the-loop
+ * approval gate; the agent writes PENDING, the ApproveTaskFn /
+ * DenyTaskFn Lambdas (Chunk 5) update to APPROVED / DENIED, and the
+ * reconciler sweeps STRANDED rows.
+ *
+ * A GSI (`user_id-status-index`) supports the `bgagent pending` access
+ * pattern — `user_id = :caller AND status = :pending` — without
+ * requiring a full-table Scan. The GSI ships in v1 because under
+ * `watch -n1`-style polling the Scan alternative would exhaust DDB
+ * burst capacity per-user (§10.1 finding #8).
+ *
+ * Streams are intentionally OFF (§11.2). TaskApprovalsTable is working
+ * state; the audit trail lives on TaskEventsTable which already has
+ * streams wired into the fan-out Lambda. Enabling streams here would
+ * create duplicate fan-out paths.
+ *
+ * TTL is sized by the agent as `created_at_epoch + timeout_s + 120s`
+ * so rows never expire during the decision window (§10.1).
+ */
+export class TaskApprovalsTable extends Construct {
+  /**
+   * The underlying DynamoDB table. Use this to grant access or read the
+   * table name.
+   */
+  public readonly table: dynamodb.Table;
+
+  /**
+   * Name of the `user_id-status-index` GSI — callers that Query the GSI
+   * should read this rather than hard-coding the string.
+   */
+  public readonly userStatusIndexName: string = USER_STATUS_INDEX_NAME;
+
+  constructor(scope: Construct, id: string, props: TaskApprovalsTableProps = {}) {
+    super(scope, id);
+
+    this.table = new dynamodb.Table(this, 'Table', {
+      tableName: props.tableName,
+      partitionKey: {
+        name: 'task_id',
+        type: dynamodb.AttributeType.STRING,
+      },
+      sortKey: {
+        name: 'request_id',
+        type: dynamodb.AttributeType.STRING,
+      },
+      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
+      timeToLiveAttribute: 'ttl',
+      pointInTimeRecoverySpecification: {
+        pointInTimeRecoveryEnabled: props.pointInTimeRecovery ?? true,
+      },
+      // NO DynamoDB stream — §11.2. TaskEventsTable is the audit fan-out
+      // path; this table holds working state only.
+      removalPolicy: props.removalPolicy ?? RemovalPolicy.DESTROY,
+    });
+
+    // GSI for GET /v1/pending — user_id PK + status SK (§10.1).
+    //
+    // Projection is INCLUDE with exactly the non-key attributes the
+    // pending-list endpoint needs: keeps per-write cost small while
+    // keeping the list response small enough to render in the CLI
+    // without additional GetItem round-trips.
+    this.table.addGlobalSecondaryIndex({
+      indexName: USER_STATUS_INDEX_NAME,
+      partitionKey: {
+        name: 'user_id',
+        type: dynamodb.AttributeType.STRING,
+      },
+      sortKey: {
+        name: 'status',
+        type: dynamodb.AttributeType.STRING,
+      },
+      projectionType: dynamodb.ProjectionType.INCLUDE,
+      nonKeyAttributes: [
+        'task_id',
+        'request_id',
+        'tool_name',
+        'tool_input_preview',
+        'severity',
+        'reason',
+        'created_at',
+        'timeout_s',
+      ],
+    });
+  }
+}

cdk/src/constructs/task-status.ts

@@ -23,11 +23,18 @@
  * States progress through the lifecycle: SUBMITTED -> HYDRATING ->
  * RUNNING -> FINALIZING -> terminal (COMPLETED / FAILED / CANCELLED / TIMED_OUT).
  * See ORCHESTRATOR.md for the full state transition table.
+ *
+ * AWAITING_APPROVAL is the Cedar-HITL soft-deny gate surface: the
+ * task is alive but paused on a human decision. See
+ * `docs/design/CEDAR_HITL_GATES.md` §10.3 for the joint
+ * `status` + `awaiting_approval_request_id` invariant that callers
+ * must preserve when transitioning in or out of this state.
  */
 export const TaskStatus = {
   SUBMITTED: 'SUBMITTED',
   HYDRATING: 'HYDRATING',
   RUNNING: 'RUNNING',
+  AWAITING_APPROVAL: 'AWAITING_APPROVAL',
   FINALIZING: 'FINALIZING',
   COMPLETED: 'COMPLETED',
   FAILED: 'FAILED',
@@ -52,22 +59,45 @@ export const TERMINAL_STATUSES: readonly TaskStatusType[] = [
 
 /**
  * Active (non-terminal) states that indicate a task is still in progress.
+ * AWAITING_APPROVAL counts as active — the task is alive, just paused
+ * waiting on a human decision.
  */
 export const ACTIVE_STATUSES: readonly TaskStatusType[] = [
   TaskStatus.SUBMITTED,
   TaskStatus.HYDRATING,
   TaskStatus.RUNNING,
+  TaskStatus.AWAITING_APPROVAL,
   TaskStatus.FINALIZING,
 ];
 
 /**
  * Valid state transitions. Maps each state to the set of states it can transition to.
- * Derived from the transition table in ORCHESTRATOR.md.
+ * Derived from the transition table in ORCHESTRATOR.md + §10.3 of the
+ * Cedar HITL gates design (AWAITING_APPROVAL entries).
  */
 export const VALID_TRANSITIONS: Readonly<Record<TaskStatusType, readonly TaskStatusType[]>> = {
   [TaskStatus.SUBMITTED]: [TaskStatus.HYDRATING, TaskStatus.FAILED, TaskStatus.CANCELLED],
-  [TaskStatus.HYDRATING]: [TaskStatus.RUNNING, TaskStatus.FAILED, TaskStatus.CANCELLED],
-  [TaskStatus.RUNNING]: [TaskStatus.FINALIZING, TaskStatus.CANCELLED, TaskStatus.TIMED_OUT, TaskStatus.FAILED],
+  [TaskStatus.HYDRATING]: [
+    TaskStatus.RUNNING,
+    TaskStatus.AWAITING_APPROVAL,
+    TaskStatus.FAILED,
+    TaskStatus.CANCELLED,
+  ],
+  [TaskStatus.RUNNING]: [
+    TaskStatus.AWAITING_APPROVAL,
+    TaskStatus.FINALIZING,
+    TaskStatus.CANCELLED,
+    TaskStatus.TIMED_OUT,
+    TaskStatus.FAILED,
+  ],
+  // AWAITING_APPROVAL transitions back to RUNNING on approve or denial
+  // resume; CANCELLED on user cancel mid-approval; FAILED only via the
+  // stranded-approval reconciler.
+  [TaskStatus.AWAITING_APPROVAL]: [
+    TaskStatus.RUNNING,
+    TaskStatus.CANCELLED,
+    TaskStatus.FAILED,
+  ],
   [TaskStatus.FINALIZING]: [TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.TIMED_OUT],
   [TaskStatus.COMPLETED]: [],
   [TaskStatus.FAILED]: [],