@anthusai/papyrus 5.42.1 → 5.43.0-next.10

package/amplify/data/schema.js

@@ -3,6 +3,7 @@ import { assignmentAction } from "../functions/assignment-action/resource.js";
 import { categoryAction } from "../functions/category-action/resource.js";
 import { editorialChecksSchemaDefinitions } from "../functions/editorial-checks/schema.js";
 import { automationViewSchemaDefinitions } from "../functions/automation-view/schema.js";
+import { proposalActionsSchemaDefinitions } from "../functions/proposal-actions/schema.js";
 import { monitoringViewSchemaDefinitions } from "../functions/monitoring-view/schema.js";
 import { contentActions } from "../functions/content-actions/resource.js";
 import { knowledgeQuery } from "../functions/knowledge-query/resource.js";
@@ -2096,6 +2097,7 @@ function buildBaseDefinitions(includeEditions) {
         ...editorialChecksSchemaDefinitions,
         ...monitoringViewSchemaDefinitions,
         ...automationViewSchemaDefinitions,
+        ...proposalActionsSchemaDefinitions,
     };
     if (!includeEditions) {
         const mutableDefinitions = definitions;

package/amplify/data/schema.ts

@@ -3,6 +3,7 @@ import { assignmentAction } from "../functions/assignment-action/resource";
 import { categoryAction } from "../functions/category-action/resource";
 import { editorialChecksSchemaDefinitions } from "../functions/editorial-checks/schema";
 import { automationViewSchemaDefinitions } from "../functions/automation-view/schema";
+import { proposalActionsSchemaDefinitions } from "../functions/proposal-actions/schema";
 import { monitoringViewSchemaDefinitions } from "../functions/monitoring-view/schema";
 import { contentActions } from "../functions/content-actions/resource";
 import { knowledgeQuery } from "../functions/knowledge-query/resource";
@@ -2225,6 +2226,7 @@ const definitions = {
   ...editorialChecksSchemaDefinitions,
   ...monitoringViewSchemaDefinitions,
   ...automationViewSchemaDefinitions,
+  ...proposalActionsSchemaDefinitions,
 };
 if (!includeEditions) {
   const mutableDefinitions = definitions as Record<string, unknown>;

package/amplify/functions/category-action/handler.ts

@@ -24,6 +24,7 @@ import {
   requestDelegation,
   type DelegationStore,
 } from "../shared/curation-delegation-flow";
+import { claimGroups } from "../../../lib/staff-groups";
 
 type ReviewHandler = Schema["reviewSteeringProposal"]["functionHandler"];
 type ReferenceCurationHandler = Schema["reviewReferenceCuration"]["functionHandler"];
@@ -360,7 +361,7 @@ function requireSignedInPerson(event: { identity?: unknown }): { sub: string; la
   }
   const identity = event.identity as { sub?: unknown; claims?: Record<string, unknown> };
   const claims = identity.claims ?? {};
-  const groups = Array.isArray(claims["cognito:groups"]) ? (claims["cognito:groups"] as unknown[]) : [];
+  const groups = claimGroups(claims["cognito:groups"]);
   return {
     sub: normalizeRequiredString(claims.sub ?? identity.sub, "identity.sub"),
     label: normalizeOptionalString(claims.email) ?? normalizeOptionalString(claims.name) ?? "Newsroom editor",

package/amplify/functions/monitoring-view/schema.js

@@ -14,12 +14,34 @@ export const monitoringViewSchemaDefinitions = {
         .returns(a.json())
         .authorization((allow) => [allow.groups(editors)])
         .handler(functionHandler("monitoringView", monitoringView)),
+    // One more page of one Monitoring list (runs, routerRuns, items, emailSubmissions), after a cursor from
+    // the overview or a previous page. filter "held" lists only held email submissions, restarting from the newest.
+    monitoringPage: a
+        .query()
+        .arguments({ list: a.string().required(), cursor: a.string(), filter: a.string(), scope: a.string() })
+        .returns(a.json())
+        .authorization((allow) => [allow.groups(editors)])
+        .handler(functionHandler("monitoringView", monitoringView)),
     monitoringEmailSubmission: a
         .query()
         .arguments({ receiptId: a.string().required() })
         .returns(a.json())
         .authorization((allow) => [allow.groups(editors)])
         .handler(functionHandler("monitoringView", monitoringView)),
+    monitoringQueueEmailReference: a
+        .mutation()
+        .arguments({ input: a.json().required() })
+        .returns(a.json())
+        .authorization((allow) => [allow.groups(editors)])
+        .handler(functionHandler("monitoringView", monitoringView)),
+    // Accept ("release") or Reject ("discard") one held email submission. The function validates the
+    // signed-in editor and that the message is routed to this publication; the receiver applies it.
+    monitoringDecideEmailSubmission: a
+        .mutation()
+        .arguments({ receiptId: a.string().required(), decision: a.string().required(), reason: a.string() })
+        .returns(a.json())
+        .authorization((allow) => [allow.groups(editors)])
+        .handler(functionHandler("monitoringView", monitoringView)),
     monitoringResolveEmailArticleLink: a
         .mutation()
         .arguments({ receiptId: a.string().required(), candidateIndex: a.integer().required() })

package/amplify/functions/monitoring-view/schema.ts

@@ -16,12 +16,34 @@ export const monitoringViewSchemaDefinitions = {
     .returns(a.json())
     .authorization((allow) => [allow.groups(editors)])
     .handler(functionHandler("monitoringView", monitoringView)),
+  // One more page of one Monitoring list (runs, routerRuns, items, emailSubmissions), after a cursor from
+  // the overview or a previous page. filter "held" lists only held email submissions, restarting from the newest.
+  monitoringPage: a
+    .query()
+    .arguments({ list: a.string().required(), cursor: a.string(), filter: a.string(), scope: a.string() })
+    .returns(a.json())
+    .authorization((allow) => [allow.groups(editors)])
+    .handler(functionHandler("monitoringView", monitoringView)),
   monitoringEmailSubmission: a
     .query()
     .arguments({ receiptId: a.string().required() })
     .returns(a.json())
     .authorization((allow) => [allow.groups(editors)])
     .handler(functionHandler("monitoringView", monitoringView)),
+  monitoringQueueEmailReference: a
+    .mutation()
+    .arguments({ input: a.json().required() })
+    .returns(a.json())
+    .authorization((allow) => [allow.groups(editors)])
+    .handler(functionHandler("monitoringView", monitoringView)),
+  // Accept ("release") or Reject ("discard") one held email submission. The function validates the
+  // signed-in editor and that the message is routed to this publication; the receiver applies it.
+  monitoringDecideEmailSubmission: a
+    .mutation()
+    .arguments({ receiptId: a.string().required(), decision: a.string().required(), reason: a.string() })
+    .returns(a.json())
+    .authorization((allow) => [allow.groups(editors)])
+    .handler(functionHandler("monitoringView", monitoringView)),
   monitoringResolveEmailArticleLink: a
     .mutation()
     .arguments({ receiptId: a.string().required(), candidateIndex: a.integer().required() })

package/amplify/functions/monitoring-view/wire.js

@@ -22,6 +22,7 @@ export function monitoringViewParameterArn(region, account) {
 export function wireMonitoringView(backend, emailMonitorId = "hn") {
     const lambda = backend.monitoringView.resources.lambda;
     const stack = Stack.of(lambda);
+    lambda.addEnvironment("PAPYRUS_USER_POOL_ISSUER", `https://cognito-idp.${stack.region}.amazonaws.com/${backend.auth.resources.userPool.userPoolId}`);
     lambda.addEnvironment("PAPYRUS_GRAPHQL_ENDPOINT", backend.data.resources.cfnResources.cfnGraphqlApi.attrGraphQlUrl);
     lambda.addEnvironment("PAPYRUS_MONITORING_TABLE_PARAMETER", MONITORING_TABLE_PARAMETER);
     lambda.addEnvironment("PAPYRUS_EMAIL_MONITOR_ID", emailMonitorId);

package/amplify/functions/monitoring-view/wire.ts

@@ -28,6 +28,7 @@ export function monitoringViewParameterArn(region: string, account: string): str
 export function wireMonitoringView(backend: any, emailMonitorId = "hn"): void {
   const lambda = backend.monitoringView.resources.lambda as LambdaFunction;
   const stack = Stack.of(lambda);
+  lambda.addEnvironment("PAPYRUS_USER_POOL_ISSUER", `https://cognito-idp.${stack.region}.amazonaws.com/${backend.auth.resources.userPool.userPoolId}`);
   lambda.addEnvironment("PAPYRUS_GRAPHQL_ENDPOINT", backend.data.resources.cfnResources.cfnGraphqlApi.attrGraphQlUrl as string);
   lambda.addEnvironment("PAPYRUS_MONITORING_TABLE_PARAMETER", MONITORING_TABLE_PARAMETER);
   lambda.addEnvironment("PAPYRUS_EMAIL_MONITOR_ID", emailMonitorId);

package/amplify/functions/procedure-action/handler.ts

@@ -3,6 +3,7 @@ import { getAmplifyDataClientConfig } from "@aws-amplify/backend/function/runtim
 import { Amplify } from "aws-amplify";
 import { generateClient } from "aws-amplify/data";
 import type { Schema } from "../../data/resource";
+import { claimGroups } from "../../../lib/staff-groups";
 
 type DataClient = ReturnType<typeof generateClient<Schema>>;
 type DataClientErrors = Array<{ message?: string | null } | string | null> | null | undefined;
@@ -474,20 +475,11 @@ function validateJsonSchemaInput(schema: Record<string, unknown>, input: Record<
 
 function requireAdmin(event: ProcedureEvent): void {
   const claims = objectValue(event.identity?.claims);
-  const groups = [
-    ...normalizeClaimGroups(claims["cognito:groups"]),
-    ...normalizeClaimGroups(claims.groups),
-  ];
+  const groups = [...claimGroups(claims["cognito:groups"]), ...claimGroups(claims.groups)];
   if (groups.includes("admin")) return;
   throw new Error("Admin role required.");
 }
 
-function normalizeClaimGroups(value: unknown): string[] {
-  if (Array.isArray(value)) return value.map((entry) => String(entry).trim()).filter(Boolean);
-  if (typeof value === "string") return value.split(",").map((entry) => entry.trim()).filter(Boolean);
-  return [];
-}
-
 async function getDataClient(): Promise<DataClient> {
   if (!clientPromise) {
     clientPromise = (async () => {

package/amplify/functions/proposal-actions/handler.py

@@ -0,0 +1,137 @@
+"""proposal-actions: the Proposals queue every newsroom backend has (editors and operators only).
+
+Behind ``fileProposal``, ``transitionProposal``, ``editProposal`` and ``listStoryDrafts``. The rules are the stdlib module
+``proposals.py`` beside this file; this file is the DynamoDB store and the AppSync entry point. The ``Proposal`` table is the
+Amplify model table written directly, so editors can list it through the data API. Reader votes on proposals and the public
+files belong to the reader-steering plugin, which reads this same table.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from datetime import datetime, timezone
+from decimal import Decimal
+from typing import Any
+
+_FUNCTION_DIRECTORY = os.path.dirname(os.path.abspath(__file__))
+if _FUNCTION_DIRECTORY not in sys.path:  # a Lambda already has its code directory on the path; a test loading this file by path does not
+    sys.path.insert(0, _FUNCTION_DIRECTORY)
+import proposals as proposal_rules  # noqa: E402
+
+PROPOSAL_TABLE_ENV = "PAPYRUS_PROPOSAL_TABLE"
+
+
+def iso(now_seconds: float) -> str:
+    """UTC with milliseconds, so rows written in the same second still sort in the order they were written."""
+    moment = datetime.fromtimestamp(now_seconds, tz=timezone.utc)
+    return moment.strftime("%Y-%m-%dT%H:%M:%S.") + f"{moment.microsecond // 1000:03d}Z"
+
+
+def plain(value: Any) -> Any:
+    if isinstance(value, Decimal):
+        return int(value) if value == value.to_integral_value() else float(value)
+    if isinstance(value, dict):
+        return {key: plain(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [plain(item) for item in value]
+    return value
+
+
+def _without_none(item: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in item.items() if value is not None}
+
+
+def is_conditional_failure(error: Exception) -> bool:
+    return str(getattr(error, "response", {}).get("Error", {}).get("Code", "")) == "ConditionalCheckFailedException"
+
+
+class DynamoProposalStore:
+    """The ``Proposal`` model table written directly: items carry ``__typename`` and ``updatedAt`` so staff can list them."""
+
+    def __init__(self, *, resource: Any, proposal_table: str) -> None:
+        self._table = resource.Table(proposal_table)
+
+    def get_proposal(self, proposal_id: str) -> dict[str, Any] | None:
+        item = self._table.get_item(Key={"id": proposal_id}, ConsistentRead=True).get("Item")
+        return plain(item) if item else None
+
+    def create_proposal(self, row: dict[str, Any]) -> bool:
+        item = {**_without_none(row), "__typename": "Proposal", "updatedAt": row["createdAt"]}
+        try:
+            self._table.put_item(Item=item, ConditionExpression="attribute_not_exists(id)")
+        except Exception as error:
+            if is_conditional_failure(error):
+                return False
+            raise
+        return True
+
+    def list_story_drafts(self, limit: int) -> list[dict[str, Any]]:
+        """The story drafts of the table, only the fields ``listStoryDrafts`` may answer; at most ``limit`` (the newest if there are more)."""
+        fields = proposal_rules.STORY_DRAFT_FIELDS
+        names = {"#kind": "kind", **{f"#f{index}": field for index, field in enumerate(fields)}}
+        request: dict[str, Any] = {
+            "FilterExpression": "#kind = :kind",
+            "ProjectionExpression": ", ".join(f"#f{index}" for index in range(len(fields))) + ", #kind",
+            "ExpressionAttributeNames": names,
+            "ExpressionAttributeValues": {":kind": "story_draft"},
+        }
+        rows: list[dict[str, Any]] = []
+        while True:
+            page = self._table.scan(**request)
+            rows.extend(plain(item) for item in page.get("Items") or [])
+            if not page.get("LastEvaluatedKey"):
+                break
+            request["ExclusiveStartKey"] = page["LastEvaluatedKey"]
+        rows.sort(key=lambda row: (row.get("createdAt") or "", row.get("id") or ""), reverse=True)
+        return [{field: row.get(field) for field in fields} for row in rows[:limit]]
+
+    def change_proposal(self, proposal_id: str, changes: dict[str, Any], expected_state: str, now_iso: str, *, expected_updated_at: str | None = None) -> bool:
+        """Apply ``changes`` if the state (and, when given, ``updatedAt``) is still what the caller saw; a value of ``None`` removes the attribute."""
+        names = {"#st": "state", "#u": "updatedAt", **{f"#c{index}": key for index, key in enumerate(changes)}}
+        sets = ", ".join(f"#c{index} = :c{index}" for index, value in enumerate(changes.values()) if value is not None)
+        removes = ", ".join(f"#c{index}" for index, value in enumerate(changes.values()) if value is None)
+        values = {":expected": expected_state, ":now": now_iso, **{f":c{index}": value for index, value in enumerate(changes.values()) if value is not None}}
+        condition = "#st = :expected"
+        if expected_updated_at is not None:
+            condition += " AND #u = :seen"
+            values[":seen"] = expected_updated_at
+        expression = f"SET {sets + ', ' if sets else ''}#u = :now" + (f" REMOVE {removes}" if removes else "")
+        try:
+            self._table.update_item(
+                Key={"id": proposal_id},
+                UpdateExpression=expression,
+                ConditionExpression=condition,
+                ExpressionAttributeNames=names,
+                ExpressionAttributeValues=values,
+            )
+        except Exception as error:
+            if is_conditional_failure(error):
+                return False
+            raise
+        return True
+
+
+def store_from_environment(environment: dict[str, str] | None = None) -> DynamoProposalStore:
+    import boto3
+
+    environment = os.environ if environment is None else environment
+    return DynamoProposalStore(resource=boto3.resource("dynamodb"), proposal_table=environment[PROPOSAL_TABLE_ENV])
+
+
+def function_account(context: Any) -> str | None:
+    """The AWS account this function runs in, from its own ARN: the only account whose IAM operators may file proposals."""
+    parts = str(getattr(context, "invoked_function_arn", None) or "").split(":")
+    return parts[4] if len(parts) > 4 and parts[4] else None
+
+
+def handle_event(event: dict[str, Any], *, store: Any, now_seconds: float, account_id: str | None = None) -> dict[str, Any]:
+    """Route an AppSync invocation to the proposal rules. Answers a receipt, never an exception."""
+    if proposal_rules.event_field_name(event) in proposal_rules.QUERIES:
+        return proposal_rules.handle_proposal_query(event, store, account_id=account_id)
+    return proposal_rules.handle_proposal_event(event, store, now_iso=iso(now_seconds), account_id=account_id)
+
+
+def handler(event: dict[str, Any], _context: Any = None) -> dict[str, Any]:
+    return handle_event(event, store=store_from_environment(), now_seconds=time.time(), account_id=function_account(_context))

package/amplify/{plugins/reader-steering/function → functions/proposal-actions}/proposals.py

@@ -92,6 +92,25 @@ def is_appsync_event(event: dict[str, Any]) -> bool:
     return "arguments" in event and ("info" in event or event_field_name(event) is not None)
 PROPOSER_AI = "ai"
 STAFF_GROUPS = frozenset({"editor", "admin"})
+
+_GROUP_SEPARATORS = re.compile(r"[\s,]+")
+
+
+def claim_groups(value: Any) -> list[str]:
+    """Copy of ``papyrus_content.staff_groups.claim_groups`` (this function ships without that package; a test keeps them equal)."""
+    if isinstance(value, (list, tuple, set, frozenset)):
+        raw = [item for item in value if isinstance(item, str)]
+    elif isinstance(value, str):
+        raw = _GROUP_SEPARATORS.split(value)
+    else:
+        return []
+    cleaned = (item.strip().strip("\"'[](){}").strip() for item in raw)
+    return [item for item in cleaned if item]
+
+
+def has_editor_rights(groups: Any) -> bool:
+    """``admin`` has every editor right: an admin who is not in the ``editor`` group is staff."""
+    return any(group.lower() in STAFF_GROUPS for group in claim_groups(groups))
 #: The only moves an operator's IAM role may make, as (from, to). Everything after the draft is an editor's decision.
 OPERATOR_TRANSITIONS = frozenset({(DRAFT, IN_STEERING), (DRAFT, DECLINED)})
 BY_STAFF, BY_OPERATOR = "staff", "operator"
@@ -140,10 +159,8 @@ def staff_subject(identity: dict[str, Any]) -> str | None:
     """The Cognito subject of an editor or admin, or ``None`` for anyone else."""
     claims = identity.get("claims") or {}
     groups = claims.get("cognito:groups") or identity.get("groups") or []
-    if isinstance(groups, str):
-        groups = [group.strip() for group in groups.strip("[]").replace(",", " ").split()]
     subject = identity.get("sub")
-    if not isinstance(subject, str) or not subject or not STAFF_GROUPS.intersection(groups):
+    if not isinstance(subject, str) or not subject or not has_editor_rights(groups):
         return None
     return subject
 

package/amplify/functions/proposal-actions/resource.js

@@ -0,0 +1,15 @@
+import { defineFunction } from "@aws-amplify/backend";
+import { Duration } from "aws-cdk-lib";
+import { Architecture, Code, Function, Runtime } from "aws-cdk-lib/aws-lambda";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const functionDirectory = path.dirname(fileURLToPath(import.meta.url));
+/** stdlib plus the runtime's boto3: the asset is this directory's two Python files and nothing else. */
+export const proposalActions = defineFunction((scope) => new Function(scope, "papyrus-proposal-actions", {
+    runtime: Runtime.PYTHON_3_12,
+    architecture: Architecture.ARM_64,
+    handler: "handler.handler",
+    timeout: Duration.seconds(25),
+    memorySize: 256,
+    code: Code.fromAsset(functionDirectory, { exclude: ["*.ts", "__pycache__", "*.pyc"] }),
+}), { resourceGroupName: "data" });

package/amplify/functions/proposal-actions/resource.ts

@@ -0,0 +1,22 @@
+import { defineFunction } from "@aws-amplify/backend";
+import { Duration } from "aws-cdk-lib";
+import { Architecture, Code, Function, Runtime } from "aws-cdk-lib/aws-lambda";
+import type { Construct } from "constructs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const functionDirectory = path.dirname(fileURLToPath(import.meta.url));
+
+/** stdlib plus the runtime's boto3: the asset is this directory's two Python files and nothing else. */
+export const proposalActions = defineFunction(
+  (scope: Construct) =>
+    new Function(scope, "papyrus-proposal-actions", {
+      runtime: Runtime.PYTHON_3_12,
+      architecture: Architecture.ARM_64,
+      handler: "handler.handler",
+      timeout: Duration.seconds(25),
+      memorySize: 256,
+      code: Code.fromAsset(functionDirectory, { exclude: ["*.ts", "__pycache__", "*.pyc"] }),
+    }),
+  { resourceGroupName: "data" },
+);

package/amplify/functions/proposal-actions/schema.js

@@ -0,0 +1,106 @@
+import { a } from "@aws-amplify/backend";
+import { proposalActions } from "./resource.js";
+import { functionHandler } from "../../data/function-handler.js";
+/**
+ * Core to every site's data API (editors and operators only; nothing here is reader-facing). Editors may list proposals;
+ * admins may also delete. The proposal-actions function writes the table with its own role. The reader-steering plugin
+ * builds on this model: it reads the table to take reader votes on proposals and to publish them in its snapshot.
+ */
+const staffOnly = (allow) => [allow.group("editor").to(["read"]), allow.group("admin").to(["read", "delete"])];
+export const proposalActionsSchemaDefinitions = {
+    Proposal: a
+        .model({
+        id: a.id().required(),
+        kind: a.string().required(),
+        title: a.string().required(),
+        summary: a.string(),
+        body: a.string().required(),
+        targets: a.json().required(),
+        evidence: a.json(),
+        proposer: a.string().required(),
+        state: a.string().required(),
+        history: a.json().required(),
+        communityResult: a.json(),
+        pinned: a.boolean(),
+        held: a.boolean(),
+        override: a.json(),
+        exclusions: a.json(),
+        editorLog: a.json(),
+        needsLook: a.json(),
+        createdAt: a.datetime().required(),
+    })
+        .disableOperations(["subscriptions"])
+        .secondaryIndexes((index) => [index("state").sortKeys(["createdAt"]).name("proposalsByState").queryField("listProposalsByStateAndCreatedAt")])
+        .authorization(staffOnly),
+    ProposalReceipt: a.customType({
+        status: a.string().required(),
+        id: a.string(),
+        error: a.string(),
+        message: a.string(),
+    }),
+    // What an operator may read of a story draft: these six fields and nothing else (no body, evidence, history, proposer, vote or log).
+    StoryDraftSummary: a.customType({
+        id: a.string().required(),
+        title: a.string().required(),
+        summary: a.string(),
+        targets: a.json(),
+        state: a.string().required(),
+        createdAt: a.string().required(),
+    }),
+    StoryDraftList: a.customType({
+        status: a.string().required(),
+        id: a.string(),
+        error: a.string(),
+        message: a.string(),
+        drafts: a.ref("StoryDraftSummary").array(),
+    }),
+    // Editors and admins file as themselves. AppSync also admits an IAM principal whose own policy allows the field (the
+    // schema accepts IAM callers for the functions that call it); the function files an AI proposal for an IAM principal
+    // of its own account only, and refuses an identity-pool user and any other account. No IAM rule is declared here.
+    fileProposal: a
+        .mutation()
+        .arguments({
+        kind: a.string().required(),
+        title: a.string().required(),
+        body: a.string().required(),
+        summary: a.string(),
+        targets: a.json(),
+        evidence: a.json(),
+    })
+        .returns(a.ref("ProposalReceipt"))
+        .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+        .handler(functionHandler("proposalActions", proposalActions)),
+    // The same IAM rule as fileProposal, narrower: an operator may move only draft to in_steering or declined.
+    // Approving, deciding after review and overriding are refused for IAM in the function (`operator_not_allowed`).
+    transitionProposal: a
+        .mutation()
+        .arguments({
+        proposalId: a.string().required(),
+        state: a.string().required(),
+        reason: a.string(),
+        result: a.string(),
+    })
+        .returns(a.ref("ProposalReceipt"))
+        .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+        .handler(functionHandler("proposalActions", proposalActions)),
+    // Read only, and the same caller rule as fileProposal: editors and admins, or an IAM principal of the function's own account. The function
+    // answers the story drafts' id, title, summary, targets, state and createdAt so an unattended run can dedupe; nothing else.
+    listStoryDrafts: a
+        .query()
+        .returns(a.ref("StoryDraftList"))
+        .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+        .handler(functionHandler("proposalActions", proposalActions)),
+    // Editors and admins only, and the function refuses an IAM operator: pin, unpin, hold, release, exclude_votes and
+    // undo_exclusion. `rule` is a batch rule for exclude_votes; `exclusionId` names the exclusion undo_exclusion reverses.
+    editProposal: a
+        .mutation()
+        .arguments({
+        proposalId: a.string().required(),
+        action: a.string().required(),
+        rule: a.string(),
+        exclusionId: a.string(),
+    })
+        .returns(a.ref("ProposalReceipt"))
+        .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+        .handler(functionHandler("proposalActions", proposalActions)),
+};

package/amplify/functions/proposal-actions/schema.ts

@@ -0,0 +1,108 @@
+import { a } from "@aws-amplify/backend";
+import { proposalActions } from "./resource";
+import { functionHandler } from "../../data/function-handler";
+
+/**
+ * Core to every site's data API (editors and operators only; nothing here is reader-facing). Editors may list proposals;
+ * admins may also delete. The proposal-actions function writes the table with its own role. The reader-steering plugin
+ * builds on this model: it reads the table to take reader votes on proposals and to publish them in its snapshot.
+ */
+const staffOnly = (allow: any) => [allow.group("editor").to(["read"]), allow.group("admin").to(["read", "delete"])];
+
+export const proposalActionsSchemaDefinitions = {
+  Proposal: a
+    .model({
+      id: a.id().required(),
+      kind: a.string().required(),
+      title: a.string().required(),
+      summary: a.string(),
+      body: a.string().required(),
+      targets: a.json().required(),
+      evidence: a.json(),
+      proposer: a.string().required(),
+      state: a.string().required(),
+      history: a.json().required(),
+      communityResult: a.json(),
+      pinned: a.boolean(),
+      held: a.boolean(),
+      override: a.json(),
+      exclusions: a.json(),
+      editorLog: a.json(),
+      needsLook: a.json(),
+      createdAt: a.datetime().required(),
+    })
+    .disableOperations(["subscriptions"])
+    .secondaryIndexes((index) => [index("state").sortKeys(["createdAt"]).name("proposalsByState").queryField("listProposalsByStateAndCreatedAt")])
+    .authorization(staffOnly),
+  ProposalReceipt: a.customType({
+    status: a.string().required(),
+    id: a.string(),
+    error: a.string(),
+    message: a.string(),
+  }),
+  // What an operator may read of a story draft: these six fields and nothing else (no body, evidence, history, proposer, vote or log).
+  StoryDraftSummary: a.customType({
+    id: a.string().required(),
+    title: a.string().required(),
+    summary: a.string(),
+    targets: a.json(),
+    state: a.string().required(),
+    createdAt: a.string().required(),
+  }),
+  StoryDraftList: a.customType({
+    status: a.string().required(),
+    id: a.string(),
+    error: a.string(),
+    message: a.string(),
+    drafts: a.ref("StoryDraftSummary").array(),
+  }),
+  // Editors and admins file as themselves. AppSync also admits an IAM principal whose own policy allows the field (the
+  // schema accepts IAM callers for the functions that call it); the function files an AI proposal for an IAM principal
+  // of its own account only, and refuses an identity-pool user and any other account. No IAM rule is declared here.
+  fileProposal: a
+    .mutation()
+    .arguments({
+      kind: a.string().required(),
+      title: a.string().required(),
+      body: a.string().required(),
+      summary: a.string(),
+      targets: a.json(),
+      evidence: a.json(),
+    })
+    .returns(a.ref("ProposalReceipt"))
+    .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+    .handler(functionHandler("proposalActions", proposalActions)),
+  // The same IAM rule as fileProposal, narrower: an operator may move only draft to in_steering or declined.
+  // Approving, deciding after review and overriding are refused for IAM in the function (`operator_not_allowed`).
+  transitionProposal: a
+    .mutation()
+    .arguments({
+      proposalId: a.string().required(),
+      state: a.string().required(),
+      reason: a.string(),
+      result: a.string(),
+    })
+    .returns(a.ref("ProposalReceipt"))
+    .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+    .handler(functionHandler("proposalActions", proposalActions)),
+  // Read only, and the same caller rule as fileProposal: editors and admins, or an IAM principal of the function's own account. The function
+  // answers the story drafts' id, title, summary, targets, state and createdAt so an unattended run can dedupe; nothing else.
+  listStoryDrafts: a
+    .query()
+    .returns(a.ref("StoryDraftList"))
+    .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+    .handler(functionHandler("proposalActions", proposalActions)),
+  // Editors and admins only, and the function refuses an IAM operator: pin, unpin, hold, release, exclude_votes and
+  // undo_exclusion. `rule` is a batch rule for exclude_votes; `exclusionId` names the exclusion undo_exclusion reverses.
+  editProposal: a
+    .mutation()
+    .arguments({
+      proposalId: a.string().required(),
+      action: a.string().required(),
+      rule: a.string(),
+      exclusionId: a.string(),
+    })
+    .returns(a.ref("ProposalReceipt"))
+    .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+    .handler(functionHandler("proposalActions", proposalActions)),
+};

package/amplify/functions/proposal-actions/wire.js

@@ -0,0 +1,10 @@
+/**
+ * Least-privilege wiring for proposal-actions: read and write on the Proposal table and nothing else, with the table's
+ * name in `PAPYRUS_PROPOSAL_TABLE`. Every site gets this, with or without the reader-steering plugin.
+ */
+export function wireProposalActions(backend) {
+    const lambda = backend.proposalActions.resources.lambda;
+    const table = backend.data.resources.tables.Proposal;
+    table.grantReadWriteData(lambda);
+    lambda.addEnvironment("PAPYRUS_PROPOSAL_TABLE", table.tableName);
+}

package/amplify/functions/proposal-actions/wire.ts

@@ -0,0 +1,13 @@
+import type { ITable } from "aws-cdk-lib/aws-dynamodb";
+import type { Function as LambdaFunction } from "aws-cdk-lib/aws-lambda";
+
+/**
+ * Least-privilege wiring for proposal-actions: read and write on the Proposal table and nothing else, with the table's
+ * name in `PAPYRUS_PROPOSAL_TABLE`. Every site gets this, with or without the reader-steering plugin.
+ */
+export function wireProposalActions(backend: any): void {
+  const lambda = backend.proposalActions.resources.lambda as LambdaFunction;
+  const table = (backend.data.resources.tables as Record<string, ITable>).Proposal;
+  table.grantReadWriteData(lambda);
+  lambda.addEnvironment("PAPYRUS_PROPOSAL_TABLE", table.tableName);
+}